cortexmem
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@cortexmem load context from my previous session"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
cortexmem
Persistent memory for AI coding agents. Zero config, works with Cursor, Claude Code, Codex, and any MCP-compatible editor.
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 initThis 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.mdStep 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_KEYis optional. It enables LLM-based session compaction viasummarize_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.
Related MCP server: Vectr
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 chunksDuring 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 overviewSession 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 chunksThe 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
cortexmem initscans your git history and codebase, chunks and embeds everything locallyEverything is stored in
.cortexmem/store.db, a single SQLite file portable across editors and machinesYour AI agent uses 4 MCP tools to search, save, and compact context
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 g7h8i9get_context()returns the pyramid overview (~500-800 tokens)get_context({ query: "..." })searches hierarchically, matching summaries first and drilling into raw chunks only when neededsummarize_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 |
Session context | Decisions, constraints, discoveries saved by the agent |
MCP Tools
Tool | When to use | What it does |
| Session start, or when you need specific context | Returns pyramid overview (no args) or hierarchical search (with |
| When the agent makes a decision, discovers something, notes a constraint | Embeds and stores instantly. Types: |
| End of session | Compacts saved context into the pyramid. Uses Claude Haiku if |
| 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 neededEnvironment Variables
Variable | Purpose | Default |
| Enables LLM compaction in | none (deterministic fallback) |
| Default max tokens for |
|
| Model for compaction |
|
Architecture
Embeddings:
all-MiniLM-L6-v2via@xenova/transformers. Runs locally, no API key needed, ~30MB modelStorage: SQLite via
sql.js(WASM). Zero native dependencies, works on any OSSearch: 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 TypeScriptLicense
MIT
Available Tools
4 toolsget_contextA
Retrieve persistent memory from previous sessions. Call at session start with no arguments to get the context pyramid: project overview, current branch summary, and recent session summaries — all in ~500-800 tokens. Use with a query to do hierarchical search: matches project → branch → session summaries first, then drills into raw chunks only when needed. Use depth to control how deep to search. Always call this first in a new session.
Inputs: depth, query, types, max_tokens.
get_statusB
Quick stats on cortexmem: total chunks stored, breakdown by type, storage location, last init time, last indexed commit.
Inputs: no named parameters.
save_contextA
Save context to persistent memory. Call this whenever you make a decision, discover something non-obvious about the codebase, agree on a constraint with the user, note WIP state, or learn a coding preference. Saved context persists across sessions and editors. Call proactively — future sessions depend on what you save now.
Inputs: content (required), context_type (required), confidence, related_files.
summarize_sessionA
Compact and persist session memory into the context pyramid. Creates a session summary from saved context, rolls it up into a branch summary, then updates the project overview. Call at end of session. Works best with ANTHROPIC_API_KEY for LLM-powered compaction; falls back to deterministic summarization without it.
Inputs: session_summary.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool targets a distinct phase of the memory lifecycle: save_context writes raw chunks, get_context reads/search, summarize_session compacts, and get_status reports stats. The only mild overlap is that both save_context and summarize_session persist data, but the descriptions clearly differentiate raw chunks from session summaries.
All tool names use a consistent snake_case verb_noun pattern: save_context, get_status, get_context, summarize_session. The verbs (save, get, summarize) are standard and predictable.
Four tools is a well-scoped, minimal set for a persistent memory server. Each tool maps to a distinct operation (write, read, summarize, status), and none feels redundant or missing at the count level.
The surface covers saving, retrieving, summarizing, and status reporting for persistent memory. However, it lacks an explicit delete/forget or edit operation, so agents cannot easily prune stale or incorrect memories — a minor but real gap.
Maintenance
Related MCP Connectors
Team memory for AI coding agents and code reviews, reviewed by humans and served over MCP.
Persistent memory for AI agents across Claude, ChatGPT and any MCP client.
Shared memory for coding agents. Stop re-explaining your codebase every session.
Persistent memory for AI agents. Semantic search, memory graph, W3C DID identity.
Related MCP Servers
- AlicenseNot gradedqualityAmaintenanceProvides persistent memory for AI coding agents via MCP, enabling agents to store and semantically recall facts, events, and lessons across sessions, all running locally without cloud dependencies.Apache 2.0
- AlicenseAqualityBmaintenanceSemantic codebase search + persistent working memory for AI code editors. Local, zero-config, MCP. No API key.2344 PyPI2MIT
- AlicenseNot gradedqualityCmaintenanceOffline-first, persistent repository memory for coding agents. Provides MCP tools for repository scanning, searching, context, and impact analysis, helping agents navigate and edit code efficiently.Apache 2.0
- AlicenseAqualityCmaintenanceLocal-first persistent memory for coding agents and MCP clients. It keeps important project context across sessions and reduces wasted tokens by retrieving only relevant memories instead of replaying unnecessary history.8MIT