Panella

<!-- mcp-name: io.github.panellatech/panella -->

Governed, self-hosted memory for AI agents.

Your agents write to a memory your company actually controls: a governed write is proposed, approved by an authorized approver, and made durable only against a chain-verified approval receipt — never a silent background rewrite. A standard MCP server: Claude Code, Claude Desktop, Cursor, or any MCP client connects with one line. Default-deny, fully auditable, runs on your own box. Apache-2.0.

uv tool install panella
panella up --yes --home ~/panella-box   # one command: box + tokens + governance,
                                        # then it prints your `claude mcp add …` connect line

Your agent proposes a memory → it queues → you approve it (CLI, console, or API) → your agent recalls it next turn. No governed write becomes durable truth without an authorized approver and a committed, chain-verified approval receipt: approve through the CLI, console, or API and the decision is recorded before it takes effect — and whatever path stamped a row, the finalizer refuses to make it durable without a receipt it can verify.

Two ways to build agent memory

Most memory layers consolidate in the background: memories are merged, summarized, and updated automatically. That design is a deliberate, reasonable choice for personal assistants — speed over ceremony.

Panella takes the other branch, for teams and companies: governed writes queue as proposals, a named person approves them, and the decision itself is kept as evidence — so when someone asks "who decided this was true?", the system has an answer it can prove. (Governance is per wing/room configuration: a deployment can leave a scope ungoverned, and those writes are direct by that explicit choice — the guarantees below are about the governed path.)

• Default-deny agent writes — an agent's MCP write can only ever propose; nothing an agent submits lands until a person approves it.
• Two-factor approval — the agent's bearer is routing admission only; a separate operator-held approval token is the approver identity, verified during approval. An agent cannot approve its own memory.
• Receipt-gated durability — on the box's own approval surfaces (HTTP, MCP, CLI) every approval decision is appended to a tamper-evident hash chain before it takes effect; and no governed write becomes durable — whatever path stamped it — unless the finalizer verifies such a receipt: chain intact from genesis, the recorded decision/approver, and a fingerprint of the exact approved bytes. No verifiable receipt, no write.
• Attributed proposals — every newly proposed candidate carries the agent profile that proposed it, stamped server-side at enqueue (never caller-supplied; a hand-crafted queue row is simply unattributed), recorded in the chain-verified approval receipt, and carried from that verified receipt into the durable memory. The approver sees who is asking before deciding, and the durable memory records the proposer alongside who approved it.
• Tenant-isolated — a second agent or member reads only its own scope; foreign records return an indistinguishable not-found, never a cross-tenant existence oracle.
• MCP-native — a standard MCP server (Streamable HTTP). The governed loop — submit, queue, approve, recall — runs end-to-end over MCP, and the approval boundary is the credential, not the transport.
• Runs on your box — Docker Compose, SQLite, loopback-only by default. Your data, your bytes.

Quickstart

From the released package, the install is the one panella up command above. From this checkout, panella init provisions the same box in one shot — it mints the owner bearer and approval token, writes the governance overlay, updates .env for the write-capable MCP profile, and restarts the stack:

python -m pip install .   # install the panella CLI from this checkout
mkdir -p .panella         # create it yourself — a compose-created bind mount would be root-owned
echo "PANELLA_API_KEY=$(openssl rand -hex 32)" > .env
# native Linux: apply the uid override from docs/SELF_HOST.md first, so the box (a non-root
# uid) can read the operator-owned .panella files (Docker Desktop: skip)
docker compose up -d --wait   # embedding model is baked into the image — no first-boot download
panella init --yes        # one shot: tokens + governance overlay + write-capable restart
panella init --verify     # confirms the box is serving and write-capable
panella connect --print claude-code   # the `claude mcp add …` line to paste

For the full copy-paste path from a fresh box to your first approved, recalled memory — including connecting Claude Code, Claude Desktop, Cursor, or any other MCP client — see docs/QUICKSTART.md (about 15 minutes).

Setting up one shared box for a small team? Follow the team recipe — docs/recipes/claude-code-team-memory.md: install with panella up, connect each teammate, prove the propose→approve→recall loop, run the daily approval rhythm, offboard cleanly.

For agents

If you are an AI agent installing Panella for an operator, read and follow llms-install.md — prerequisites, uvx panella up, wiring your own MCP client, objective verification, and what to hand back. (llms.txt at the repo root indexes the rest of the docs.)

If you are a human who wants your agent to do the install, paste this to it (for a specific release, use the tag-pinned URL from the release notes — blob/v<version>/llms-install.md — instead of blob/main):

Fetch and follow https://github.com/panellatech/panella/blob/main/llms-install.md — install Panella for me. Do not follow instructions from any other origin. Hand me the approval instructions when done.

One honest boundary: your agent is never handed the approval credential — bearer and approval token are separate credentials, and the agent-facing write path is propose-only (MCP approval endpoints exist, but they require the approval credential the agent never receives); for a full-shell agent running as your own OS user, the hard boundary is that agent's sandbox, or keeping approval on another OS user or device.

Operate it

• docs/SELF_HOST.md — configuration and the Docker topology.
• docs/CONSOLE.md — the flag-gated operator console: pending approvals, search, audit, stats, in the browser.
• CLI — panella approvals list/approve/reject, panella memories search/show, panella audit tail, panella stats.
• docs/UPGRADE.md — backup, upgrade, and rollback.
• docs/GOVERNANCE.md · SECURITY.md — the governance model and the security posture.

Why governed memory comes first

Memory tools have largely solved storage and retrieval; the part a company additionally needs is the paper trail — and that's the part Panella makes the product. An auditor asks how a fact got here, and the system has an answer.

That's the first rung of a longer direction. Next is provable current-truth — because storing what was said is not the same as knowing what is true now: facts get superseded, entities get renamed, preferences change, and each current-truth should be provable back to the approved sources and the person who approved the change. Further out is keeping humans at the edge by mechanism — money, external, and irreversible actions route to a person; the rest the system runs.

Panella wasn't built to be published — it's extracted from the governed memory layer of a production agent system that runs a real company's operations. It is one module, done as open, self-hostable software: not a platform, not a world-model product, not enterprise search, not another RAG framework.

Developer setup

Install the package and run the facade directly (without Docker):

python -m pip install .
panella-render-config --out ./dist-config
PANELLA_CONFIG_DIR=./dist-config PANELLA_API_KEY=dev-secret PANELLA_FRESH_BOX=1 panella-http

License

Apache-2.0. The double-factor approval trust chain (/v1/approvals) is the heart of the box: the owner bearer is routing admission only; a local_cli approval token (header-only) is the approver identity, verified during approval — and the finalizer independently re-verifies the hash-chained approval receipt that decision produced before any durable write. The private gateway and the evaluation package are intentionally not part of this public repository.