Cortexmem

Persistent memory for AI coding agents. Zero config, works with Cursor, Claude Code, Codex, and any MCP-compatible editor.

npm version License: MIT Node.js >= 18

AI coding agents lose all context when a session ends. CortexMem fixes this by building a semantic memory store from your git history, codebase, and session context, then making it searchable via MCP tools.

Setup

Step 1: Initialize your project

cd your-project
npx cortexmem init

This scans your git history and codebase, embeds everything locally, and stores it in .cortexmem/store.db. It also generates editor config files (CLAUDE.md, .cursorrules, codex.md) that instruct AI agents to use cortexmem automatically.

First run downloads the embedding model (~30MB, one-time). Subsequent runs are incremental and only re-index new commits and changed files.

$ 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.

You can optionally include a project spec or requirements doc:

npx cortexmem init ./PROJECT.md

Step 2: Add to your editor's MCP config

Cursor (add to ~/.cursor/mcp.json):

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

Claude Code (add to ~/.claude.json or project settings):

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

With LLM-powered compaction (optional, add your Anthropic API key):

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

Restart your editor. CortexMem is running.

ANTHROPIC_API_KEY is optional. It enables LLM-based session compaction via summarize_session. Without it, everything else works and compaction uses a deterministic fallback.

Step 3: There is no step 3

The generated editor config files (CLAUDE.md, .cursorrules, codex.md) instruct your AI agent to use cortexmem automatically. It will:

• Load context from previous sessions on startup
• Save decisions, discoveries, and constraints as you work
• Compact memory at session end

No manual tool calls needed.

Example: What a session looks like

Session 1: You start working on auth

Your AI agent automatically calls get_context at session start:

## 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

During work, the agent saves context automatically:

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)

At session end, the agent calls 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

Session 2: Different day, context is preserved

The agent calls get_context and immediately has full 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

The agent can also search for specific context:

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...

Re-running init (incremental)

When you come back after more commits:

$ 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)

How It Works

1. cortexmem init scans your git history and codebase, chunks and embeds everything locally
2. Everything is stored in .cortexmem/store.db, a single SQLite file portable across editors and machines
3. Your AI agent uses 4 MCP tools to search, save, and compact context
4. Context is organized in a pyramid: project, branch, and session summaries with raw chunks underneath

The Context Pyramid

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() returns the pyramid overview (~500-800 tokens)
• get_context({ query: "..." }) searches hierarchically, matching summaries first and drilling into raw chunks only when needed
• summarize_session() rolls up: session chunks → session summary → branch summary → project summary

What Gets Indexed

Source	What's Extracted
Git log	Commit messages, descriptions, file change patterns
Source files	Code structure, functions, classes, patterns
Config files	Stack, tooling, dependencies
Docs (.md)	Documentation content
Project file	Specs, requirements (via cortexmem init <file>)
Session context	Decisions, constraints, discoveries saved by the agent

MCP Tools

Tool	When to use	What it does
get_context	Session start, or when you need specific context	Returns pyramid overview (no args) or hierarchical search (with query). Depth 0-3 controls granularity.
save_context	When the agent makes a decision, discovers something, notes a constraint	Embeds and stores instantly. Types: decision, constraint, state, discovery, preference.
summarize_session	End of session	Compacts saved context into the pyramid. Uses Claude Haiku if ANTHROPIC_API_KEY is set, deterministic fallback otherwise.
get_status	Anytime	Quick stats: chunk counts by type, storage location, last init time.

Context Types

Type	Purpose	Example
decision	Architectural/technical choices	"Chose PostgreSQL over MongoDB for ACID transactions"
constraint	Hard rules to never violate	"Never modify auth middleware directly"
state	Current WIP status	"Payment refactor: 2/4 services done"
discovery	Non-obvious codebase facts	"UserService is called from 6 places, not 3"
preference	Code style conventions	"Snake_case for variables, PascalCase for classes"

CLI Commands

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

Portability

CortexMem stores everything in a single file: .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

Environment Variables

Variable	Purpose	Default
ANTHROPIC_API_KEY	Enables LLM compaction in summarize_session	none (deterministic fallback)
CORTEXMEM_MAX_TOKENS	Default max tokens for get_context	3000
CORTEXMEM_MODEL	Model for compaction	claude-haiku-4-5-20251001

Architecture

• Embeddings: all-MiniLM-L6-v2 via @xenova/transformers. Runs locally, no API key needed, ~30MB model
• Storage: SQLite via sql.js (WASM). Zero native dependencies, works on any OS
• Search: Hybrid keyword + vector search. Keywords by default, vector when model is warm. Both work offline.
• Transport: MCP stdio. Works with any MCP-compatible editor

Development

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

License

MIT