ctx-memory
ctx-memory
为 LLM 编码代理(Claude Code、Codex、Gemini CLI、OpenCode)提供的持久化内存。
当你开始一个新的会话时,代理已经知道你上次做了什么:做出的决策、修改的文件、遇到的错误、学到的约定。无云端,无遥测。所有数据都存储在 ~/.ctx-memory/store.db 的本地 SQLite 数据库中。
工作原理
Session starts
│
Shell wrapper intercepts 'claude' (or codex/gemini/opencode)
│
MCP server starts alongside — injects prior context, exposes memory tools
│
During session: hooks fire on every tool call, messages buffered
│
Session ends (clean exit / Ctrl-C / crash)
│
Layer 1 → Layer 2 → Layer 3 pipeline runs
│
├── Layer 1: extract weighted messages, events, decisions, errors, keywords
├── Layer 2: compress to ≤500-token digest, store in DB
└── Layer 3: merge digest into project memory doc (markdown)
Next session: agent reads prior context automaticallyRelated MCP server: remem
安装
npm install -g ctx-memory
ctx-memory setup设置向导:
检测已安装的工具(
claude、codex、gemini、opencode)询问需要集成的工具
为每个工具写入钩子配置
在
~/.ctx-memory/bin/中创建包装器符号链接通过
~/.bashrc/~/.zshrc将~/.ctx-memory/bin添加到你的 PATH 中
重启你的 shell(或执行 source ~/.bashrc),然后像往常一样使用你的工具 —— 内存是自动化的。
命令
ctx-memory setup # interactive setup wizard
ctx-memory status # show configuration and stats
ctx-memory projects list # list all projects
ctx-memory projects show <name> # print full memory doc for a project
ctx-memory projects forget <name> # reset memory (keeps sessions)
ctx-memory projects forget <name> --hard # delete all sessions + dataMCP 服务器
MCP 服务器作为每个工具会话的辅助进程运行,并公开六个工具:
工具 | 描述 |
| 缓存对话消息以便在会话结束时处理 |
| 记录工具调用事件(文件编辑、bash 命令等) |
| 通过语义相似度或关键词搜索过去的会话 |
| 返回完整的项目内存文档 |
| 列出带有目标和结果的近期会话 |
| 结束会话并运行第 1 层 → 第 2 层 → 第 3 层流水线 |
若要将 MCP 服务器与 Claude Code 独立使用,请添加到 ~/.claude/settings.json:
{
"mcpServers": {
"ctx-memory": {
"command": "node",
"args": ["/path/to/ctx-memory/dist/src/mcp/index.js"]
}
}
}架构
src/
cli/ — setup wizard, status, projects commands
db/ — SQLite schema + CRUD (projects, sessions, events, digests, memory)
layer1/ — pure message/event processing → weighted Layer1Output
layer2/ — digest compression to ≤500 tokens → Layer2Digest
layer3/ — merge digest into ProjectMemory markdown
mcp/ — MCP server (handlers + stdio entry point)
wrapper/ — shell wrapper (intercepts tool invocation, manages session lifecycle)
hooks/ — hook config writers for Claude / Gemini / OpenCode关键约束:
所有第 1/2/3 层函数都是纯函数 —— 无 I/O,从不抛出异常
摘要保持在 500 token 以内
向量搜索使用通过
sqlite-vec实现的 all-MiniLM-L6-v2 嵌入(384 维)单个 SQLite 数据库,WAL 模式,开启外键约束
开发
npm run build # tsc → dist/
npm run dev # tsc --watch
npm run test:run # vitest (single-shot, 476+ tests)
npm test # vitest (watch mode)数据库路径默认为 ~/.ctx-memory/store.db。可通过 CTX_MEMORY_DB_PATH 进行覆盖。
许可证
MIT
Available Tools
6 toolsend_sessionC
Signal session end — runs Layer 1→2→3 pipeline, stores digest, updates project memory.
Inputs: outcome (required), project_id (required), session_id (required), exit_code.
get_project_memoryC
Return the full project memory document (architecture, conventions, recent work, known issues).
Inputs: project_id.
list_sessionsC
List recent sessions for a project with their goals and outcomes.
Inputs: limit, project_id.
search_contextB
Search past sessions for context relevant to a query. Uses embedding similarity, falls back to keyword search.
Inputs: query (required), limit, project_id.
store_eventC
Record a tool call event (file edit, bash command, etc.) for the current session.
Inputs: tool (required), session_id (required), args, result, +1 more.
store_messageC
Buffer a conversation message for session-end processing.
Inputs: role (required), index (required), content (required), session_id (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool has a clearly distinct purpose: session lifecycle (end_session), memory retrieval (get_project_memory, list_sessions, search_context), and data recording (store_event, store_message). No overlap in functionality.
All tool names follow a consistent verb_noun pattern using snake_case, e.g., end_session, get_project_memory, store_event. The naming is predictable and uniform.
With 6 tools, the server covers core memory management operations without bloat. The count is well-scoped for the domain of session context and project memory.
The tool surface covers the full typical lifecycle: recording events/messages, searching and retrieving context, listing sessions, and finalizing sessions with memory updates. No obvious gaps.
Maintenance
Related MCP Connectors
Persistent cross-session memory shared by Codex, Claude Code, ChatGPT, and other AI agents.
Shared memory for coding agents. Stop re-explaining your codebase every session.
Persistent memory for AI agents — shared .brain across Claude Code, Cursor & Codex
Persistent memory for AI agents: one brain shared across Claude, Cursor, Codex and more.
Related MCP Servers
- AlicenseBqualityBmaintenancePersistent, local memory for AI coding agents that learns how you work, not just what you said. Supports Claude Code, Codex CLI, Cursor, and any MCP client.7998 PyPI77MIT
- AlicenseAqualityAmaintenanceLocal-first persistent memory for Claude Code and OpenAI Codex CLI. A single Rust binary captures, distills, searches, and injects project memory across sessions via hooks, MCP, CLI, and localhost REST.1533MIT
- FlicenseNot gradedqualityCmaintenancePersistent, self-curating memory for coding agents. It enables local, zero-cost context recall through MCP tools with hybrid retrieval and autonomous consolidation.-
- FlicenseNot gradedqualityBmaintenancePersistent memory for AI coding agents: local-first semantic search, dependency graphs, git history.1-