copal

<p align="center"> <img src="brand/copal-lockup-horizontal.png" alt="Copal" width="380"> </p>

<p align="center"><strong>A self-hosted, headless personal knowledge hub — a persistent memory layer for your LLM assistants.</strong></p>

Copal is an open-source second brain that sits between your AI assistants (Claude, ChatGPT, agents like Hermes, n8n) and stores everything they capture, so nothing is ever lost and any assistant can pick up where another left off. It exposes one tool surface — an MCP server (Model Context Protocol) plus a REST mirror — that N conversational clients read and write through. Copal itself doesn't chat; it remembers.

Named after copal — tree resin that hasn't yet fossilized into amber. Like amber, it preserves what falls into it.

Keywords: personal knowledge management (PKM), second brain, self-hosted note-taking, LLM memory, AI agent memory, Hermes agent harness, MCP server, Model Context Protocol, knowledge graph, semantic search, vector search, embeddings, RAG, headless CMS for thoughts, Postgres, pgvector, TypeScript.

---

The idea

Two regimes joined by one link graph:

• A rigid spine — boards of work items with declared statuses (a monday.com-style tracker). Work has state.
• A fluid material — ideas, conversation sessions, and captured content. Thoughts flow; they have no status column, just a trail.

And one promise: nothing is ever deleted. Entities can sink out of the foreground but stay in the corpus forever — searchable, embeddable, and resurfaceable. Declared state is dangerous for thoughts and correct for work; Copal makes that literal.

Features

• 🧠 One memory, many clients. A single MCP + REST surface. Point Claude, ChatGPT, an agent framework, or a script at it — none of them owns your memory.
• 🔗 Everything is a linkable object. Ideas, items, sessions, and content connect to anything; explore your knowledge as a graph.
• 🔎 Semantic search + resonance. Every capture self-embeds (pgvector, HNSW cosine); a nightly Librarian surfaces discovered connections between related material as advisory suggestions.
• 🪶 A calm background worker. The Housekeeper distills conversation transcripts into resumable handoff summaries and catalogues content — on a configurable model chain with automatic failover and a hard daily spend cap.
• 📝 Markdown-native reader, board drag-and-drop, inline-editable cells, file attachments, and a clean Linear-style console.
• 🧾 Append-only audit log — every mutation records who / what / when (metadata-only, so secrets in free text never land in the log).
• 🩺 Operable by default — a /status deep health-check (WAL archiving, worker liveness, spend, queues), CI, and a documented backup/restore runbook.
• 🔒 Yours. Self-hosted; per-client hashed bearer tokens with read/write/admin scopes; corpus-derived text is treated as inert data, never as instructions.

How it works

LLM clients (Claude · ChatGPT · Hermes · n8n)
        │  MCP (Streamable HTTP) + REST
        ▼
   ┌──────────────────────────────┐
   │  Copal core (Node + Fastify) │  ← the one tool surface; never converses
   │  · boards/items (the spine)  │
   │  · ideas/sessions/contents   │
   │  · polymorphic link graph    │
   │  · Housekeeper (summaries)   │
   │  · Librarian (resonance)     │
   └──────────────┬───────────────┘
                  ▼
     PostgreSQL 16 + pgvector  (+ WAL archiving for backups)

• Backend: Node 22 + TypeScript, Fastify, Drizzle ORM, the official MCP SDK.
• Store: PostgreSQL 16 with pgvector (full-text now, semantic vectors always).
• Console: Vite + React 19 + Tailwind — a fast SPA served by the same process.
• AI: a configurable, provider-agnostic model chain (Google Gemini / Anthropic / add your own) for summaries; OpenAI embeddings for search. All optional — capture works with no keys at all.

Quick start

See SETUP.md for the full walkthrough. In short:

cp .env.example .env          # set DATABASE_URL (+ optional AI keys)
psql "$DATABASE_URL" -c "CREATE EXTENSION IF NOT EXISTS vector;"
npm ci
npm run db:migrate
npm run db:seed               # optional: a starter workspace + example board
npm run mint-token -- me read,write,admin
npm run build && npm start    # serves the API + console on :8787

Open the console, paste your token, and you're in. Connect any MCP client to /mcp (or the REST API at /api/v1) with a token.

Give it a voice — Hermes is the recommended harness

Copal is deliberately headless: it remembers, but it doesn't converse. To give it a conversational front-end, pair it with an agent harness — and Hermes is the one Copal is designed around and recommends. The pattern:

• during a conversation, the agent writes facts live through Copal's MCP tools (ideas, items, links, sessions);
• when the conversation ends, a small Hermes capture plugin (included) posts the full transcript to Copal as a safety net — so nothing is lost even if the model forgot to save.

Any MCP-capable client works (Claude, ChatGPT, your own agents), but Hermes + Copal is the intended pairing: a capable, tool-using agent up front, a durable memory behind it.

Design & docs

• DESIGN.md — the principles (intelligence at the edge, one tool surface, nothing is deleted, corpus inertness).
• SETUP.md — install & first run.
• docs/DATA-FLOWS.md — exactly what data leaves for which AI provider, and why.
• ops/ — backup / restore runbook.

Status

Early but daily-driven and hardened: migrations, tests, CI, an audit log, and a /status monitor endpoint are in place. APIs may still shift before a tagged release. Contributions and issues welcome.

License

Code is MIT. The Copal name and logo are not covered by the MIT license — copyright and trademark in the identity belong to the project owner; see brand/ and brand/LICENSE-ASSETS.md.