agentic-cortex: Long-Term Memory for Coding Agents
TL;DR: AI coding agents forget everything between sessions. The bug you debugged for 3 hours. The architecture decision. The Windows gotcha. agentic-cortex gives them persistent, searchable, self-improving memory across sessions and projects — entirely local, zero API costs, 368 tests passing.
Why I Built This
A few months ago, I started using Claude Code, OpenCode, and Codebuff daily. Every session began the same way: re-teaching the agent about my project's context, re-stating decisions I'd already made, and watching it make the same mistakes from last week. Chat history helps, but it doesn't prevent errors from repeating or encode the why behind architectural choices.
I wanted my agents to learn — not just remember conversations, but build a real knowledge base that improves over time and transfers across projects. So I built agentic-cortex.
What It Does
Core Memory Engine
- 13 typed memories: instruction, fact, decision, goal, commitment, preference, relationship, context, event, learning, observation, artifact, error
- Confidence scoring (0–100) + provenance tracking (explicit, inferred, observed)
- BGE 768-dim embeddings with hybrid FTS5+semantic search and cross-encoder reranking
- Save-time deduplication: cosine similarity ≥ 0.97 → reinforce existing memory instead of duplicating
-
Temporal queries:
--changed-since,--as-ofdate filters
Zero-Arg Bootstrap
agentic-cortex bootstrap
No arguments. Infers your task from the git branch, session prompt, or recent activity. Returns structured XML with actionable insights, tiered relevant memories, recent sessions, warnings about stale memories, collapsed coding standards, the codebase graph, and the machine-wide global vault — all in one call. Auto-starts a session if none is active.
Auto Type Detection
Pattern-matches content to classify as error, decision, learning, preference, fact, instruction, event, or goal. No --type flag needed unless you want to override.
agentic-cortex save "TypeError: Cannot read properties of undefined (reading 'map')"
# → auto-detected as type: error, confidence: 95
Machine-Wide Global Vault
Learnings from Project A automatically protect agents in Projects B, C, D. Think of it as a cross-project immune system:
- Auto-promotion using relative thresholds (top 20% confidence, 2× median utility) — self-tunes as projects grow
-
Manual promotion:
agentic-cortex promote-global <id> -
Cross-project search:
agentic-cortex machine-search "query" -
Analytics:
agentic-cortex machine-memory --analytics
Self-Improving Loop
- Error RCA: detects errors and generates systemic learnings via LLM root cause analysis
- Conflict detection: finds contradictions using semantic similarity + LLM resolution
- Evidence-based confidence: tracks intent → action → outcome triplets and adjusts scores accordingly
- Freshness scoring (0–100): combines access recency, confidence, and utility — auto-archives stale memories
- Auto-maintenance scheduler: runs every ~50 saves, minimum 6 hours between cycles
Codebase Graph
Deterministic static analysis — zero LLM cost, SHA-256 cached. Extracts files, exports, imports, function signatures, API routes, Prisma schemas, architectural layers (UI/API/Service/Data), paradigms, and tech stack. Outputs structured XML optimized for LLM token efficiency (~4× fewer tokens than equivalent markdown). Auto-injected on git checkout, merge, pull, and commit via hooks.
Agent-Optimized Output
-
knowledge.mdis XML-structured and token-optimized for LLM consumption - Discovery files auto-created for Claude Code, Cursor, and OpenCode
- MCP server with 39+ tools over stdio JSON-RPC — zero config, no HTTP port
- Pre-loaded coding standards (DRY, KISS, SOLID, Clean Code, Karpathy) — always injected
Additional Intelligence
- Grounded QA: retrieve relevant memories + LLM answer with source citations
- Transcript ingestion: regex + LLM extracts decisions, errors, and learnings from conversations
- Skill/procedure extraction with structured fields (triggers, preconditions, steps, postconditions)
- Daily summaries with LLM + template fallback
- Obsidian export with wikilinks and tag indexes
- File watcher daemon for auto-capture
- HTTP API server on port 37777
Feature Comparison
| Capability | agentic-cortex | LangChain Memory | ChromaDB / Pinecone | Mem0 | Cursor Rules |
|---|---|---|---|---|---|
| Typed memory categories | 13 | 1 (messages) | 0 (raw vectors) | ~6 | 0 (static text) |
| Confidence + provenance scoring | ✓ | ✗ | ✗ | ✓ | ✗ |
| Semantic + hybrid search | ✓ | ✗ | ✓ | ✓ | ✗ |
| Save-time deduplication | ✓ | ✗ | ✗ | ✗ | ✗ |
| Auto type detection | ✓ | ✗ | ✗ | ✗ | ✗ |
| Zero-arg bootstrap | ✓ | ✗ | ✗ | ✗ | ✗ |
| Error → learning RCA loop | ✓ | ✗ | ✗ | ✗ | ✗ |
| Conflict detection + resolution | ✓ | ✗ | ✗ | ✗ | ✗ |
| Cross-project knowledge transfer | ✓ | ✗ | ✗ | ✗ | ✗ |
| Codebase graph (static analysis) | ✓ | ✗ | ✗ | ✗ | ✗ |
| Git hook auto-injection | ✓ | ✗ | ✗ | ✗ | ✗ |
| Freshness scoring + auto-archival | ✓ | ✗ | ✗ | ✗ | ✗ |
| MCP server (39+ tools) | ✓ | ✗ | ✗ | ✗ | ✗ |
| Pre-loaded coding standards | ✓ | ✗ | ✗ | ✗ | ✓ |
| Runs entirely local (no API costs) | ✓ | ✓ | ✓ | ✓ | ✓ |
| Grounded QA with citations | ✓ | ✗ | ✗ | ✗ | ✗ |
Key Differentiators
vs. LangChain Memory: LangChain provides message buffers. agentic-cortex provides a full knowledge lifecycle — typed memories with confidence decay, automatic error-to-learning pipelines, cross-project knowledge transfer, and a self-improving loop that runs without configuration.
vs. Vector DBs (ChromaDB, Pinecone): Vector databases store embeddings. agentic-cortex stores knowledge — typed, scored, versioned, cross-referenced, and self-improving. Vector DBs are a building block; agentic-cortex is the finished house.
vs. Mem0: agentic-cortex adds zero-arg bootstrap with task inference, a machine-wide global vault with self-tuning promotion, deterministic codebase graph generation, conflict detection via semantic+LLM, freshness scoring with auto-archival, and 13 memory types (versus Mem0's ~6 broader categories).
vs. Cursor Rules / Manual Context Files: Static .cursorrules files don't adapt. agentic-cortex auto-persists memory with semantic search, confidence decay over time, cross-project transfer, evidence-based utility scoring, and a self-improving RCA loop. You stop maintaining context files; the agent starts building its own knowledge.
The Stack
Node.js · SQLite (single DB per machine) · Xenova BGE embeddings (entirely local) · Hybrid FTS5+semantic search · Cross-encoder reranking · Optional llama.cpp for LLM summarization
Get Started
npm install -g agentic-cortex
agentic-cortex bootstrap
368 tests passing. MIT licensed. Free and fully open-source.
If your agents keep reinventing the same solutions every session, give them a memory system that persists, self-improves, and protects across projects.
Top comments (0)