Banyan.Mcp.Server

English | 中文版

🌳 Banyan Brain Lite

Stable 1.5.1 — an offline-first, governed memory and knowledge node for AI agents, backed by SQLite.

Banyan Brain Lite is an event-sourced memory store that agents can Remember(), Search(), Update(), and Forget() against. It speaks the NPS-3 Memory Node surface through NPS.NWP, uses Ed25519 NIDs issued by a local or remote NIP CA, and provides an OLS/OIDC operator identity track for human administrators.

The current source tree is the stable 1.5.1 Banyan governed memory and knowledge release.

What is in 1.5.1

• Hybrid retrieval — BM25 / FTS5 + ONNX vector search + RRF fusion. When sqlite-vec is available, vector search uses ANN; otherwise it falls back to in-memory cosine.
• Offline semantic embeddings — pluggable IEmbedder, bge-small-zh-v1.5 ONNX support, and a hashing fallback for fully offline operation.
• Event-sourced memory — immutable write/update/forget log plus a current snapshot table for fast reads.
• NPS Memory Node compatibility — banyan serve exposes /.nwm, /.schema, and POST /api/memory/query through the NWP Memory Node middleware.
• NID authentication — Authorization: NID <base64(IdentFrame)>, with anonymous-allowed, writes-required, and all-required modes.
• Embedded NIP Mini-CA — local certificate issuance, verification, revocation, and NPS-3 §8 compatible HTTP routes.
• Remote CA support — a Lite node can verify identities issued by a remote nip-ca-server using --trusted-issuer and --ocsp-url.
• Operator identity — OLS/OIDC-backed admin setup, login, JWT, and SQLite-backed identity stores.
• Web UI — memory and Wiki search/write UI using the shared packable Governance component library, with real detail drawers, lifecycle and access summaries, permission-filtered provenance traces, responsive narrow-screen layout, agent and CA operations, first-run admin setup, and login enforcement.
• MCP server — stdio MCP via banyan mcp and Streamable HTTP MCP at /mcp when running banyan web.
• Governed Wiki — editable tree-structured knowledge with strong ETags, SQLite FTS, source-version lineage, policy bindings, and authorization-before-body reads.
• Governance reconciliation — bounded body-free scans report current objects without governance and materialized governance without objects as hash-only repair items; scoped file-backed Pack mounts are included.
• Source authorization contracts — file/Pack snapshots, revalidation, live-source checks, Pro Pool groups, and Ent Enterprise IAM share a fail-closed gate for narrowing, TTL, group changes, and adapter outages.
• Audited policy simulator — canonical policy.evaluate requires Admin visibility, reads body-free descriptors, never mutates policy, and withholds explanations if its hash-only audit cannot be persisted.
• Optional disclosure grounding — a default-off quality stage can annotate or further filter already-authorized claims; it cannot grant access or restore policy-filtered content.
• Explicit retention and purge — durable archive/purge jobs are epoch-bound and leased; purge removes bodies, indexes, and last-reference governance blobs before writing a body-free receipt and tamper-evident audit.
• Knowledge packs — .banyanpack v2 signing, mount trust through the NID/CA chain, in-pack vector recall, and pack version pin / upgrade / rollback.
• Observability and audit — Lite OpenTelemetry wiring, memory-operation metrics, and tamper-evident local audit records.
• Single-binary CLI — installable as a .NET tool with memory, CA, agent, embedder, web, MCP, and NWP commands.

Try MCP in 5 minutes

For a local L0 evaluation, no model download, CA, admin account, or separate server is required:

dotnet tool install -g Banyan.Mcp.Server --version 1.5.1
banyan-mcp

The public MCP-only tool has a closed public NuGet dependency graph. It creates ~/.banyan/memory.db, uses the offline hashing embedder, and prints a ready-to-paste mcpServers block for Claude Desktop and Cursor. The MCP client can immediately call remember, then search, through the same governed Application pipeline used by the other Lite transports.

Windows users can instead open banyan-memory-1.5.1-win-x64.mcpb from the GitHub release for one-click Claude Desktop installation. The same server is published as io.github.labacacia/banyan-memory in the official MCP Registry.

Quick mode is intentionally local and trusted. Move to the full setup below when you need ONNX retrieval, NID agent identity, browser administration, or Ivy Hub integration. OpenTelemetry distinguishes the paths with banyan.lite.mcp_starts{mode="quick|standard"}.

Full governed setup

# 0. Install the full Banyan Brain Lite 1.5.1 Windows or Debian release,
#    then verify the CLI.
banyan --version

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

# 2. Bootstrap the embedded NID CA
export BANYAN_NIP_CA_PASSPHRASE='your-passphrase'
banyan ca init

# 3. Create an admin account from CLI, or use the browser setup flow later
banyan init --admin-username admin --admin-password 'change-me-now'

# 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

Release artifacts include a per-user Windows installer with an Add/Remove Programs uninstaller (banyan-lite-1.5.1-setup.exe) and a Debian package (banyan-lite_1.5.1_amd64.deb). When upgrading a legacy 1.1.x machine-wide Windows installation, setup requests elevation to remove the old Program Files copy before continuing with the current per-user installation.

Back up memory.db together with memory.db.claim-kek. Stop Banyan before a filesystem copy, or use SQLite's online backup API to produce a consistent WAL snapshot. Claim statements are envelope-encrypted; a database restored without its matching key file is intentionally unreadable.

On startup, banyan web and banyan serve resumably backfill legacy Memory rows as legacy_unknown provenance and legacy Wiki rows as local manual provenance. Progress is checkpointed in SQLite after each item. Operators can preview or bound the run with BANYAN_GOVERNANCE_BACKFILL_DRY_RUN, BANYAN_GOVERNANCE_BACKFILL_BATCH_SIZE, BANYAN_GOVERNANCE_BACKFILL_ITEMS_PER_SECOND, and BANYAN_GOVERNANCE_BACKFILL_MAX_ITEMS_PER_RUN. Set BANYAN_GOVERNANCE_BACKFILL_RESTART=true only for an intentional full rescan, such as after running an older binary during a rollback window.

Disclosure quality is disabled by default and therefore performs no supporting body load. Set BANYAN_DISCLOSURE_QUALITY_MODE=advisory to retain authorized claims with a bounded quality assessment, or required to keep only claims reported as supported. BANYAN_DISCLOSURE_QUALITY_TIMEOUT_MS defaults to 2000 (100..30000), and BANYAN_DISCLOSURE_GROUNDING_MIN_COVERAGE defaults to 0.8 (0..1). Lite currently wires the local lexical evaluator, which receives only the redacted claim and a claim-bounded signal derived from authorized content, not the full supporting body. It is a low-cost grounding signal rather than a semantic entailment authority. All modes run after authorization and can only narrow output. The timeout is a hard wait boundary even when a custom loader or evaluator ignores cancellation; enabled modes fail at startup when either dependency is missing.

To run as a pure NWP Memory Node without the web UI:

banyan serve --allow-anon
# GET  /.nwm
# GET  /.schema
# POST /api/memory/query

To register the same governed actions with Ivy Hub through Ivy.ActNode.Sdk 0.2.12-alpha, enable the SDK runtime on the banyan serve process. Lite's configured tenant/workspace must remain _local/default unless the node governance scope is changed with the matching host options.

export IVY_ACT_NODE_ENABLED=true
export IVY_ACT_NODE_HUB_URL=http://127.0.0.1:17880
export IVY_ACT_NODE_ACCESS_TOKEN='<node-access-token>'
export IVY_ACT_NODE_TENANT_ID=_local
export IVY_ACT_NODE_WORKSPACE_ID=default
banyan serve --nid-auth writes-required

The SDK owns registration, WebSocket reconnect, catalog updates, heartbeat, and invocation decoding. /api/act remains the separate NPS HTTP Action endpoint.

To require NID authentication for writes:

banyan web   --nid-auth writes-required
banyan serve --nid-auth writes-required

To verify certificates from a remote CA instead of using the embedded CA:

banyan web --no-ca \
  --trusted-issuer "urn:nps:ca:<ca-nid>=ed25519:<ca-pubkey>" \
  --ocsp-url http://your-ca-host:17435/ocsp

To connect Codex to Banyan's native Web MCP endpoint:

codex mcp add banyan-lite --url http://localhost:5180/mcp

Use as agent memory

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 [hit["content"] for hit in r.json()["hits"] if hit["score"] > threshold]

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

Recommended pattern: recall before each agent turn, and write only on explicit signals such as "remember this", user corrections, durable preferences, or decisions. See docs/recipes/agent-memory.md for namespace design, thresholds, write triggers, NID-attested mode, failure recovery, and anti-patterns.

Project structure

src/
├── Banyan.ActNode      # shared Ivy Act Node SDK lifecycle host
├── Banyan.Core         # IMemoryStore, IEmbedder, request/response records
├── Banyan.Lite         # SQLite memory store, BM25, vector search, RRF
├── Banyan.Embedders    # HashingEmbedder, OnnxEmbedder, EmbedderFactory
├── Banyan.Auth         # Embedded NIP CA, SQLite CA store, RemoteNipCaClient
├── Banyan.Identity     # OLS/OIDC human identity on SQLite
├── Banyan.Web          # ASP.NET Core Web UI + memory/agent/identity/CA REST APIs
├── Banyan.Mcp          # MCP tools and transport integration
├── Banyan.Mcp.Server   # public zero-config MCP-only .NET tool
├── Banyan.Node         # NWP Memory Node host
└── Banyan.Cli          # banyan .NET tool

tests/
├── Banyan.Core.Tests
├── Banyan.Lite.Tests
├── Banyan.Auth.Tests
├── Banyan.Identity.Tests
└── Banyan.Node.Tests

Documentation

Document	Description
docs/release/1.5.1.md	Release notes and verification status for Banyan Brain Lite 1.5.1
docs/release/1.5.0.md	Historical release notes for Banyan Brain Lite 1.5.0
docs/release/1.1.0.md	Release notes and operational checklist for Banyan Brain Lite 1.1.0
docs/release/1.0.0.md	Historical release notes for Banyan Brain Lite 1.0.0
docs/client-integration-profile.md	Portable client profile for switching between Lite, Pro, and Ent
docs/knowledge-base.md	Governed Lite Wiki records, canonical API routes, ETags, and provenance
docs/recipes/mcp-server.md	Claude Desktop / Claude Code MCP integration
docs/recipes/agent-memory.md	Connecting an agent to Banyan through HTTP
docs/client-integration-profile.md	Public Lite integration and capability profile
ADR-001: Shared memory pools	Canonical Pool scope, membership, and edition boundaries
docs/architecture/storage-tiers.md	SQLite memory, identity, and CA storage layout
docs/architecture/nps-mapping.md	How Banyan maps to NPS-3 NCP / NWP / NIP
docs/architecture/identity.md	Dual-track identity: NID for machines, OLS/OIDC for humans

Edition boundary

This repository is the Lite distribution. Lite is Apache-2.0, single-node, SQLite-backed, and suitable for local agent memory, small deployments, demos, and embedded/offline workloads.

Commercial editions and enterprise deployment options are maintained separately. For commercial licensing or enterprise deployment, contact INNO LOTUS PTY LTD.

Built on

• LabAcacia.NPS.{Core,NIP,NWP} — Neural Protocol Suite stack
• labacacia/nip-ca-server — remote NIP CA server
• InnoLotus.Root.{Core,Authentication,Authorisation,Oidc} — human-side identity stack
• Microsoft.ML.OnnxRuntime + Microsoft.ML.Tokenizers — ONNX inference and WordPiece tokenization
• Xenova/bge-small-zh-v1.5 — multilingual sentence embeddings
• asg017/sqlite-vec — SQLite vector index

License

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