Skip to main content
Glama

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 automatically

Related MCP server: remem

安装

npm install -g ctx-memory
ctx-memory setup

设置向导:

  1. 检测已安装的工具(claude、codex、gemini、opencode)

  2. 询问需要集成的工具

  3. 为每个工具写入钩子配置

  4. 在 ~/.ctx-memory/bin/ 中创建包装器符号链接

  5. 通过 ~/.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 + data

MCP 服务器

MCP 服务器作为每个工具会话的辅助进程运行,并公开六个工具:

工具

描述

store_message

缓存对话消息以便在会话结束时处理

store_event

记录工具调用事件(文件编辑、bash 命令等)

search_context

通过语义相似度或关键词搜索过去的会话

get_project_memory

返回完整的项目内存文档

list_sessions

列出带有目标和结果的近期会话

end_session

结束会话并运行第 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 tools
end_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

    B3.3/5.0

    Scored across 6 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers