Banyan.Core 0.1.0-alpha.1

English | 中文版

🌳 Banyan

A memory node for AI agents — speaks the NPS wire protocol, stores everything in SQLite, runs entirely offline.

Banyan is an event-sourced memory store that agents can Remember(), Search(), Update() and Forget() against. The wire protocol is NPS-3 — Neural Web Protocol Memory-Node middleware via NPS.NWP, identity via Ed25519 NIDs from the NIP CA, and a parallel OIDC track for human operators on top of OLS.

Features

• Hybrid retrieval — BM25 (FTS5) + ONNX vector search + RRF fusion. Vector index uses sqlite-vec ANN when available, falls back to in-memory cosine.
• Real semantic embeddings — pluggable IEmbedder; ships with bge-small-zh-v1.5 (multilingual, 22 MB INT8 ONNX, 384-dim) plus an offline hashing fallback.
• Dual-track identity
  • Agents / Memory Nodes: Ed25519 NID certificates issued by an embedded NipCaService or a remote nip-ca-server. Banyan ships the NPS-3 §8 conformant HTTP routes that the NPS.NIP NuGet hasn't shipped yet.
  • Operators / Admins: OIDC + JWT via OLS, with a SQLite-backed implementation of every Identity / OAuth store interface. The web UI enforces login via redirect when identity is configured.
• Real NID authentication in Lite — Authorization: NID <base64(IdentFrame)> middleware with three modes (anonymous-allowed / writes-required / all-required). Server-side verified NID overrides any client-supplied agentNid; revocations from the CA take effect immediately.
• Event-sourced memory — every Write/Update/Forget appends to an immutable log; the latest snapshot lives in memories_current; trace stays auditable even after forget.
• Standards-compliant Memory Node — banyan serve mounts app.UseMemoryNode<TProvider>, exposes /.nwm (NeuralWebManifest), /.schema, POST /api/memory/query (NWP frames with anchor_ref, token_est, etc.).
• Web UI — neon-glass, particle-network background, three-tab SPA (Memory · Agents · About). Requires login when identity is configured; anonymous memory reads/writes remain available via the API without a session.
• MCP Server — banyan mcp runs as a Model Context Protocol stdio server, giving Claude Desktop and Claude Code four first-class memory tools (recall, remember, update, forget) with zero system-prompt boilerplate.
• Single-binary CLI — dotnet tool install -g Banyan.Cli ships the entire surface (keygen, init, login, ca init, agent issue/verify/revoke, embedder download, mcp, web, serve).

Quick Start

# 0. Install
dotnet tool install -g Banyan.Cli

# 1. Pull the embedder model + sqlite-vec extension (~24 MB)
banyan embedder download

# 2. Bootstrap human-side identity (creates admin account and JWT signing key)
banyan keygen
banyan init

# 3. Bootstrap the NID CA (skip if using an external CA server)
export BANYAN_NIP_CA_PASSPHRASE='your-passphrase'
banyan ca init

# 4. Issue an agent certificate
banyan agent issue --id summarizer-01 --cap memory.read,memory.write \
  --key-out ~/.banyan/agents/summarizer-01.key

# 5. Start the web UI
export BANYAN_EMBEDDER=onnx
banyan web
# → open http://localhost:5180
# → redirects to /login.html when identity is configured (step 2)
# → sign in with the admin account to access agent management and CA ops
# → without step 2, memory reads/writes work anonymously via the API

# To connect to an external nip-ca-server instead of the embedded one:
banyan web --no-ca \
  --trusted-issuer "urn:nps:ca:<ca-nid>=ed25519:<ca-pubkey>" \
  --ocsp-url http://your-ca-host:17435/ocsp

# 6. Enable NID authentication (writes-required is the common production setting)
banyan web   --nid-auth writes-required
banyan serve --nid-auth writes-required
# POST/PUT/DELETE/PATCH require Authorization: NID <base64(IdentFrame)>; reads stay open

# 7. Or run as a pure NWP Memory Node (no web UI)
banyan serve --allow-anon
# → POST /api/memory/query with QueryFrame body
# → GET  /.nwm for the NeuralWebManifest

# 8. Remote CA: issue / verify / revoke from another host
export BANYAN_CA_URL=https://your-ca-host:5180
banyan agent issue --id offsite-agent --cap memory.read --remote $BANYAN_CA_URL
banyan agent verify urn:nps:agent:.../offsite-agent --remote $BANYAN_CA_URL

Use as agent memory

If you're an agent author plugging Banyan into Claude / GPT / your own assistant:

import requests

def recall(query: str, user_id: str, threshold: float = 0.50) -> list[str]:
    r = requests.get("http://banyan-host:5180/api/memory/search",
                     params={"q": query, "mode": "hybrid", "k": 5,
                             "namespace": f"user-{user_id}"}, timeout=2)
    return [h["content"] for h in r.json()["hits"] if h["score"] > threshold]

def remember(fact: str, user_id: str, agent_nid: str | None = None):
    requests.post("http://banyan-host:5180/api/memory", json={
        "content": fact, "namespace": f"user-{user_id}", "agentNid": agent_nid,
    }, timeout=2)

Recall before every turn, write only on explicit signals (the user says "remember X", corrects you, or pins a decision). Full integration guide in docs/recipes/agent-memory.md — covers namespace design, threshold heuristics, write triggers, NID-attested mode, failure recovery, anti-patterns.

Project Structure

src/
├── Banyan.Core         # IMemoryStore, IEmbedder, request/response records
├── Banyan.Lite         # SqliteMemoryStore (BM25 + cosine + RRF + sqlite-vec ANN)
├── Banyan.Embedders    # HashingEmbedder, OnnxEmbedder, EmbedderFactory
├── Banyan.Auth         # NID CA: EmbeddedNipCa, SqliteNipCaStore, RemoteNipCaClient
├── Banyan.Identity     # OLS-backed human identity (OIDC, JWT, RBAC) on SQLite
├── Banyan.Web          # ASP.NET Core web UI + agents/memory/identity REST,
│                         + NPS-3 §8 NIP CA HTTP routes (gap-fill for the NuGet)
├── Banyan.Node         # banyan serve — NPS.NWP MemoryNodeMiddleware host
└── Banyan.Cli          # `banyan` dotnet tool

tests/
├── Banyan.Core.Tests       (5)
├── Banyan.Lite.Tests       (42, incl. 6 ONNX + 5 sqlite-vec)
├── Banyan.Auth.Tests       (46, incl. 7 RemoteNipCaClient + 10 NID middleware)
├── Banyan.Identity.Tests   (43)
└── Banyan.Node.Tests       (8)

Documentation

Built On

• LabAcacia.NPS.{Core,NIP,NWP} — Neural Web Protocol stack
• labacacia/nip-ca-server — NIP CA server (Docker + Postgres)
• OLS.Root.{Core,Authentication,Authorisation,Oidc} — human-side identity stack
• Microsoft.ML.OnnxRuntime + Microsoft.ML.Tokenizers — ONNX inference + BERT WordPiece
• Xenova/bge-small-zh-v1.5 — multilingual sentence embeddings
• asg017/sqlite-vec — SQLite ANN vector index

License

Apache-2.0. Copyright © 2026 INNO LOTUS PTY LTD.