Zenod

An open-source AI memory agent with self-hosted and managed-hosted modes.

Zenod is the interface between AI agents and your personal knowledge vault. Self-hosted Zenod uses ordinary Markdown in your own GitHub repository; Zenod Hosted can use either a user-owned GitHub repository or an app-created Google Drive vault, with real Git history in either case. Agents talk to Zenod through MCP; Zenod reads and writes the vault on their behalf, enforcing its organization rules so memory compounds instead of rotting.

Named after Zenodotus of Ephesus, first librarian of the Library of Alexandria.

Philosophy: self-hosted, user-owned

This repository contains both the open-source self-hosted Zenod runtime and the shared hosted runtime deployed at cloud.zenod.dev. The deal is simple:

• Your vault. Plain markdown in a git repo in your GitHub account. Exportable with zero data loss — it's just files. Open it in Obsidian any time.
• Your server. One Docker container on your own VPS (we deploy ours with Dokploy). One volume for state. No external services required beyond GitHub and the Anthropic API.
• Your keys. You bring your own Anthropic API key and GitHub token. They live on your box, configured through Zenod's own settings UI.
• Auditable memory. Every memory Zenod stores is a git commit in your vault. git log is the audit trail; every fact has a provenance link back to the evidence that produced it.

The hosted service uses the same engine and image with tenant-scoped storage, encrypted credential custody, Google or GitHub sign-in, user-selected Drive or GitHub vault authority, Stripe billing, and fail-closed production-readiness checks. GitHub issue/code tasking remains an optional connection; memory and local Markdown backlog work do not require it. Self-hosting does not depend on the hosted customer layer: if you can run a container, you never need the hosted service.

What Zenod does

Two roles, one engine (full doctrine in docs/LIBRARIAN-DOCTRINE.md):

1. The librarian — runs on every message. Files the verbatim evidence (append-only, immutable, block-ID citations), then updates the living meaning pages (Areas, Projects, Notes) that the evidence touches, with a citation link for every claim. When unsure where something belongs, it asks instead of guessing.
2. The compactor (later milestone) — runs periodically. Merges duplicates, connects pages, tightens bloat. Adds no information.

Agents never get raw file CRUD. The write path is the product.

Status

Early access / hosted beta. The engine, REST API, authenticated remote MCP endpoint, settings UI, Docker image, multi-tenant hosted runtime, GitHub onboarding, subscription lifecycle, billing portal, and production-readiness gate are implemented. Public paid signup remains closed automatically unless live billing, legal version, tax handling, support contact, and a recent restore verification are all configured.

Quick start (self-host)

docker build -t zenod .
docker run -d --name zenod -p 8080:8080 -v zenod-data:/data zenod

Open http://localhost:8080 and the setup wizard takes it from there: create an admin password, connect your vault repo with a GitHub fine-grained PAT (Contents: read & write), add your Anthropic API key, and copy the MCP connection snippet. All state — settings, conversation history, and the vault clone — lives on the single /data volume. If your vault is a plain Obsidian vault, Zenod adds the machine schema (.brain/config.yml, Areas/, templates) on first connect with a schema: v1 commit.

Connect Claude Code to the deployed instance:

claude mcp add --transport http zenod https://your-host/mcp --header "Authorization: Bearer <token from settings>"

Architecture at a glance

┌─────────────────────────── one container ───────────────────────────┐
│                                                                      │
│  Web UI (React/Vite/shadcn) ──┐                                      │
│  MCP endpoint (Streamable HTTP)├──► Brain engine ──► vault workdir   │
│  HTTP API / CLI ──────────────┘    store · ask · chat     │          │
│                                    search · get · lint    │ git      │
│  SQLite (settings, conversations,                         ▼          │
│  job queue) on a volume                          your GitHub vault   │
└──────────────────────────────────────────────────────────────────────┘

• Engine spec: docs/M0-SPEC.md
• Vault rules: docs/LIBRARIAN-DOCTRINE.md
• Self-test chat harness: docs/SELF-TEST-HARNESS.md
• C1 deployment discipline: docs/C1-DEPLOYMENT.md
• Hosted production gate: docs/PRODUCTION-READINESS.md
• Stack: TypeScript / Node 22+, Claude Agent SDK, simple-git, ripgrep, SQLite, React + Vite + shadcn/ui.

License

AGPL-3.0. Your vault content is yours; this license covers the code.