jeonjw85/kenfold

English | Korean
**One memory for all your AI agents.** Bring every agent into the fold.
Claude Code, Codex, OpenCode, ChatGPT, and local models each keep their own memory. Kenfold is a self-hosted memory server they all share over MCP: a decision made in one tool is known in the next.
The main design choices (see ADR-0001):
- **Typed memory**: semantic, episodic, project, preference, codebase, temporary, each with its own lifecycle
- **Provenance**: every memory records which agent wrote it (from its API key, not from what the client claims), when, and how far to trust it
- **No silent overwrites**: a replacement supersedes the old memory, which is kept as history
- **Handoff** between agents: stop in Claude Code, resume in Codex
- **Poisoning-aware**: memory is served as data, never as instructions; preferences need your approval
> **Status: Phase 5 features implemented; public benchmark validation incomplete.** Shared storage, hybrid search, session hooks, memory extraction, code references, OAuth remote access, export/import, a review dashboard, and consolidation are implemented. The latest scored run preserved partial raw-LoCoMo results for 1,402/1,540 questions, then stopped on unknown API usage. Extracted-LoCoMo and LongMemEval QA were not scored; no complete benchmark result is claimed. See the qualified partial results and accounting.
Quickstart
Requirements: Docker with Compose. Go 1.27+ only for development.
make up gives full-text search. For better search, which also finds memories phrased differently from the query, run the local search models instead:
Memories written without embeddings are embedded automatically once a model is available. The reranker reads the query and each candidate memory together; on the internal eval set it raised recall@5 from 0.90 to 0.96 (see Search quality), at the cost of 1–2 seconds per search on CPU. make up-embed RERANK=0 leaves it out.
Upgrading
A release build checks GitHub for a newer version and shows it in the dashboard footer and in kenfold version. It does not download or restart. KENFOLD_UPDATE_CHECK=false turns the check off.
Connect your agents
Each agent uses its own key. The key decides the agent name recorded on every memory.
**Claude Code**
**Codex** (~/.codex/config.toml); set KENFOLD_CODEX_KEY in the environment Codex starts from:
For the desktop app or IDE extension, which may not see your shell environment, use http_headers = { "Authorization" = "Bearer kf_..." } instead.
**OpenCode** (opencode.json in a project, or ~/.config/opencode/opencode.json):
**stdio** (the client starts Kenfold as a subprocess): build with make build, then run bin/kenfold mcp with KENFOLD_AGENT set to the agent's name. The stdio server connects to the database directly (KENFOLD_DATABASE_URL, default: the compose database), so it does not use API keys and the agent name is whatever you configure.
With make up-embed, also set KENFOLD_EMBED_URL=http://127.0.0.1:11435/v1 for stdio servers.
**ChatGPT, claude.ai, and other machines** need a public HTTPS URL, behind a tunnel or a reverse proxy, with KENFOLD_PUBLIC_URL set:
This turns on Kenfold's OAuth 2.1 server. ChatGPT and claude.ai find it on their own, and you approve each on a consent page, read-only or read and write. Agents with API keys use the public URL as before. See docs/deploy.md for Tailscale Funnel, Cloudflare Tunnel, and Caddy, and read its checklist before exposing your memory to the internet.
Session hooks (Claude Code, Codex)
MCP tools only run when the model decides to call them. Hooks make memory automatic:
- **Session start**: the hook loads memory for the current repository (pending handoff, recent sessions, project knowledge, preferences) and gives it to the model as context.
- **During the session**: your requests, the final response, and Claude Code's compaction summary are recorded in a local log (~/.local/state/kenfold, readable only by you, secrets redacted). This adds no network calls.
- **Session end**: the log becomes a short session summary (an episodic memory), so the next agent, in any tool, knows what happened. If Kenfold is down, the summary is kept and sent at the next session start.
Sessions outside a git repository are not recorded. The hook never blocks the agent: problems are reported as a warning.
Queued summaries are bound to the original server URL, client name, and configured credential. A different agent or server cannot send them. Older, unbound queue files are kept with a warning rather than guessing their owner; queued files expire after 30 days.