English | [中文版](./README.cn.md)

# 🌳 Banyan Brain Lite

<!-- mcp-name: io.github.labacacia/banyan-memory -->

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

[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](./LICENSE)
[![Version](https://img.shields.io/badge/version-1.5.2-orange)]()
[![Status](https://img.shields.io/badge/status-stable-green)]()

Banyan Brain Lite is an event-sourced memory store that agents can `Remember()`, `Search()`, `Update()`, and `Forget()` against. It speaks the [NPS-3](https://github.com/labacacia/NPS-Release) Memory Node surface through [`NPS.NWP`](https://www.nuget.org/packages/LabAcacia.NPS.NWP), uses Ed25519 NIDs issued by a local or remote [NIP CA](https://github.com/labacacia/nip-ca-server), and provides an OLS/OIDC operator identity track for human administrators.

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

---

## What is in 1.5.2

- **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.
- **Product update tracking** — the About page can run an Admin-only,
  opt-in manifest check through `InnoLotus.ProductUpdater.Web`; see
  [`product-update-checks.md`](../../docs/operations/product-update-checks.md).
- **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, version pin / upgrade / rollback, and last-reference snapshot uninstall.
- **Knowledge workspace** — a permission-filtered Wiki tree plus a full-screen AntV G6 knowledge atlas for documents, blocks, tags, backlinks, and governed block-to-document traces. Restricted resources remain body-free shadows.
- **Personal and appearance settings** — local credential changes revoke the active session, while Admin-only validated backgrounds customize the shared Portal without weakening same-origin or authorization checks.
- **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:

```bash
dotnet tool install -g Banyan.Mcp.Server --version 1.5.2
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.2-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"}`.

When HTTP MCP or REST writes are exposed without NID/CA authentication, set
`BANYAN_MCP_TOKEN` or pass `--mcp-token` and send the value as an
`Authorization: Bearer` token. This gates `/mcp` and mutating `/api/memory`
requests while keeping authenticated Portal sessions and read-only memory
integrations working.

## Full governed setup

```bash
# 0. Install the full Banyan Brain Lite 1.5.2 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.2-setup.exe`) and a Debian package
(`banyan-lite_1.5.2_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:

```bash
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.15-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.

```bash
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:

```bash
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:

```bash
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:

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

## Use as agent memory

```python
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`](./docs/recipes/agent-memory.md) for namespace design, thresholds, write triggers, NID-attested mode, failure recovery, and anti-patterns.

## Project structure

```text
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.2.md`](./docs/release/1.5.2.md) | Release notes and verification status for Banyan Brain Lite 1.5.2 |
| [`docs/release/1.5.1.md`](./docs/release/1.5.1.md) | Historical release notes for Banyan Brain Lite 1.5.1 |
| [`docs/release/1.5.0.md`](./docs/release/1.5.0.md) | Historical release notes for Banyan Brain Lite 1.5.0 |
| [`docs/release/1.1.0.md`](./docs/release/1.1.0.md) | Release notes and operational checklist for Banyan Brain Lite 1.1.0 |
| [`docs/release/1.0.0.md`](./docs/release/1.0.0.md) | Historical release notes for Banyan Brain Lite 1.0.0 |
| [`docs/client-integration-profile.md`](./docs/client-integration-profile.md) | Portable client profile for switching between Lite, Pro, and Ent |
| [`docs/knowledge-base.md`](./docs/knowledge-base.md) | Governed Lite Wiki records, canonical API routes, ETags, and provenance |
| [`docs/recipes/mcp-server.md`](./docs/recipes/mcp-server.md) | Claude Desktop / Claude Code MCP integration |
| [`docs/recipes/agent-memory.md`](./docs/recipes/agent-memory.md) | Connecting an agent to Banyan through HTTP |
| [`docs/client-integration-profile.md`](./docs/client-integration-profile.md) | Public Lite integration and capability profile |
| [ADR-001: Shared memory pools](../../docs/architecture/adr-001-memory-pools.md) | Canonical Pool scope, membership, and edition boundaries |
| [`docs/architecture/storage-tiers.md`](./docs/architecture/storage-tiers.md) | SQLite memory, identity, and CA storage layout |
| [`docs/architecture/nps-mapping.md`](./docs/architecture/nps-mapping.md) | How Banyan maps to NPS-3 NCP / NWP / NIP |
| [`docs/architecture/identity.md`](./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}](https://github.com/labacacia/NPS-Release) — Neural Protocol Suite stack
- [labacacia/nip-ca-server](https://github.com/labacacia/nip-ca-server) — remote NIP CA server
- [InnoLotus.Root.{Core,Authentication,Authorisation,Oidc}](https://github.com/orilynn-studio/ols-root) — human-side identity stack
- [Microsoft.ML.OnnxRuntime](https://onnxruntime.ai/) + Microsoft.ML.Tokenizers — ONNX inference and WordPiece tokenization
- [Xenova/bge-small-zh-v1.5](https://huggingface.co/Xenova/bge-small-zh-v1.5) — multilingual sentence embeddings
- [asg017/sqlite-vec](https://github.com/asg017/sqlite-vec) — SQLite vector index

## License

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