cortexmem (Ashprakash)

皮质

AI编码代理的持久内存。Zero配置，适用于Cursor、Claude Code、Codex和任何兼容MCP的编辑器。

当会话结束时，AI编码代理会失去所有上下文。CortexMem通过从git历史、代码库和会话上下文构建语义内存存储来解决这个问题，然后通过MCP工具进行搜索。

设置

步骤1：初始化项目

cd your-project
npx cortexmem init

这会扫描你的git历史和代码库，在本地嵌入所有内容，并将其存储在 .cortexmem/store.db。它还生成编辑器配置文件(CLAUDE.md, .cursorrules, codex.md)指示AI代理自动使用cortexmem。

第一次运行下载嵌入模型（约30MB，一次性）。后续运行是 渐进的 并且只重新索引新的提交和更改的文件。

$ npx cortexmem init

CortexMem — initializing context for /Users/you/my-project

Full scan — first-time initialization...
  Found 142 commits → 87 chunks
  Found 38 files → 52 chunks

Embedding 139 chunks...
Storing in database...
Building project summary...
Generating editor configs...
  Created: CLAUDE.md, .cursorrules, codex.md
Done!

Summary:
  Git commits indexed: 142
  Source files scanned: 38
  Total chunks stored: 139

Storage: /Users/you/my-project/.cortexmem/store.db

Add to your MCP config to start using cortexmem with your AI agent.

您可以选择包含项目规范或需求文档：

npx cortexmem init ./PROJECT.md

步骤2：添加到编辑器的MCP配置中

光标 （添加到 ~/.cursor/mcp.json):

{
  "mcpServers": {
    "cortexmem": {
      "command": "npx",
      "args": ["-y", "cortexmem"]
    }
  }
}

克劳德代码 （添加到 ~/.claude.json 或项目设置）：

{
  "mcpServers": {
    "cortexmem": {
      "command": "npx",
      "args": ["-y", "cortexmem"]
    }
  }
}

采用LLM动力压实 （可选，添加您的Anthropic API密钥）：

{
  "mcpServers": {
    "cortexmem": {
      "command": "npx",
      "args": ["-y", "cortexmem"],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

重新启动编辑器。CortexMem正在运行。

ANTHROPIC_API_KEY 是可选的。它通过以下方式实现基于LLM的会话压缩 summarize_session没有它，其他一切都能正常工作，压缩使用确定性回退。

步骤3：没有步骤3

生成的编辑器配置文件(CLAUDE.md, .cursorrules, codex.md)指示您的AI代理自动使用cortexmem。它将：

• 启动时加载以前会话的上下文
• 在工作时保存决策、发现和约束
• 会话结束时的紧凑型内存

无需手动调用工具。

示例：会话是什么样子的

会话1：开始进行身份验证

您的AI代理会自动调用 get_context 会话开始时：

## CortexMem Context — my-project
Initialized: 2026-03-08T10:30:00Z

### Project Overview
my-project: Node.js/TypeScript API server. 142 commits, 38 files.
Stack: Express, PostgreSQL, Jest. Main modules: auth, payments, users.

### Index Stats
- Commit Summaries: 87 chunks
- Code Summaries: 52 chunks

在工作过程中，代理会自动保存上下文：

save_context({
  context_type: "decision",
  content: "Using JWT with refresh tokens for auth. Access tokens expire in 15min, refresh tokens in 7 days. Stored in httpOnly cookies, not localStorage.",
  related_files: ["src/auth/jwt.ts", "src/middleware/auth.ts"]
})
→ Saved decision context (id: 12, session: a1b2c3, branch: main)

save_context({
  context_type: "constraint",
  content: "Auth middleware must never be modified directly. Extend via plugins in src/auth/plugins/",
  related_files: ["src/middleware/auth.ts"]
})
→ Saved constraint context (id: 13, session: a1b2c3, branch: main)

save_context({
  context_type: "state",
  content: "Auth implementation: JWT service done, middleware done, refresh token rotation TODO",
  related_files: ["src/auth/jwt.ts"]
})
→ Saved state context (id: 14, session: a1b2c3, branch: main)

在会话结束时，代理调用 summarize_session:

summarize_session({ session_summary: "Implemented JWT auth with refresh tokens" })
→ Compaction complete:
  Session: Compacted 3 entries into session summary
  Branch (main): Updated branch summary
  Project: Updated project overview

会话2：不同的日子，上下文得以保留

代理人打电话来 get_context 并且立即具有完整的上下文：

## CortexMem Context — my-project

### Project Overview
my-project: Node.js/TypeScript API with JWT auth (access + refresh tokens),
PostgreSQL, Express. Auth module complete, payment refactor in progress.

### Branch: main
JWT auth implemented with httpOnly cookies. Auth middleware uses plugin
architecture (never modify directly). Refresh token rotation still TODO.

### Recent Sessions (main)
#### Session a1b2c3 (2026-03-08)
Implemented JWT authentication with refresh tokens. Access tokens expire
in 15min, refresh in 7 days. Created plugin-based auth middleware.
Refresh token rotation is the next task.

### Index Stats
- Decisions: 1 chunks
- Constraints: 1 chunks
- State: 1 chunks
- Commit Summaries: 87 chunks
- Code Summaries: 52 chunks

代理还可以搜索特定上下文：

get_context({ query: "auth middleware", depth: 3 })
→ ## CortexMem Context — my-project
  Query: "auth middleware" | depth: 3

  ### [project > branch:main > session:a1b2c3] (87% match)
  JWT auth with refresh tokens. Plugin-based middleware architecture.

  **Details:**
  - [Constraint] Auth middleware must never be modified directly. Extend via plugins
  - [Decision] Using JWT with refresh tokens for auth. Access tokens expire in 15min...

重新运行init（增量）

当您在更多提交后返回时：

$ npx cortexmem init

CortexMem — initializing context for /Users/you/my-project

Incremental update — scanning changes since last init...
  8 new commits → 6 chunks
  3 files changed
  3 changed files → 4 chunks

Embedding 10 chunks...
Storing in database...
Building project summary...
Done!

Summary (incremental):
  Git commits indexed: 8 (new)
  Source files scanned: 38
  Total chunks stored: 10 (new)

运作原理

1. cortexmem init 扫描你的git历史和代码库，将所有内容块化并嵌入到本地
2. 一切都存储在 .cortexmem/store.db，一个可跨编辑器和机器移植的SQLite文件
3. 您的AI代理使用4个MCP工具来搜索、保存和压缩上下文
4. 上下文以某种方式组织 金字塔：项目、分支和会话摘要，下面有原始块

上下文金字塔

Project Summary              ← "What is this project about?"
├── Branch: main             ← "What's happening on main?"
│   ├── Session a1b2c3       ← "What did we do 2 days ago?"
│   └── Session d4e5f6       ← "What did we do yesterday?"
└── Branch: feature/payments ← "What's the payments work?"
    └── Session g7h8i9

• get_context() 返回金字塔概览（约500-800个代币）
• get_context({ query: "..." }) 分层搜索，首先匹配摘要，仅在需要时钻取原始块
• summarize_session() 卷起：会话块→ 会议摘要→ 分支摘要→ 项目概要

什么被索引

MCP工具

上下文类型

命令行命令

cortexmem init [project-file]   Scan git history + codebase, build context store
                                 Incremental on re-run, only indexes new changes
cortexmem inject          Inject/update a project file (spec, requirements)
cortexmem status                Show what's stored
cortexmem                       Start MCP server (used by AI editors)

可移植性

CortexMem将所有内容存储在一个文件中： .cortexmem/store.db

# Move to a new machine
scp .cortexmem/store.db user@newmachine:~/project/.cortexmem/

# Share with teammates (commit it)
git add .cortexmem/store.db

# Switch editors, same file works everywhere
# Claude Code -> Cursor -> Codex, no migration needed

环境变量

建筑

• 嵌入: all-MiniLM-L6-v2 通过 @xenova/transformers.本地运行，不需要API密钥，约30MB型号
• 存储：SQLite通过 sql.js （WASM）。零原生依赖，适用于任何操作系统
• 搜索：混合关键字+矢量搜索。默认情况下为关键字，模型处于热态时为向量。两者都离线工作。
• 运输：MCP标准。可与任何兼容MCP的编辑器配合使用

发展

git clone https://github.com/Ashprakash/cortexmem.git
cd cortexmem
npm install
npm test          # run 106 tests
npm run dev       # run with tsx
npm run build     # compile TypeScript

许可证

麻省理工学院