banyan-brain-lite

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

# 🌳 Banyan Brain Lite

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

> Stable 1.5.1 — 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.1-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.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:

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

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

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

```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},