Semantic memory for AI coding agents

Give your AI assistant persistent memory that learns from your project's history.

Features • Installation • Quick Start • Tools • Best Practices • Architecture

---

The Problem

AI coding assistants are incredibly powerful, but they have a critical limitation: they forget everything between sessions. Every time you start a new conversation, your AI assistant has no memory of:

• Past architectural decisions and why they were made
• Patterns that work well in your codebase
• Approaches that failed and should be avoided
• Project-specific rules and guardrails

You end up repeating context, re-explaining decisions, and sometimes watching the AI make the same mistakes twice.

Why not just use CLAUDE.md?

The typical solution is adding context to .md files. It doesn't scale:

• Context window has limits — your instructions compete with actual code
• Loads everything even when you only need part of it
• No semantic search ("state management" won't find "Zustand")
• Can't learn from failures or evolve automatically

The Solution

code-recall is an MCP server that gives AI agents persistent, semantic memory. It stores observations, decisions, and learnings in a local SQLite database with vector search capabilities, allowing your AI to:

• Remember past decisions and their outcomes
• Learn from failures (failed approaches are boosted in future searches)
• Follow rules with semantic matching guardrails
• Understand your code structure through tree-sitter analysis

All data stays local on your machine. No cloud, no telemetry, fully private.

---

Features

Semantic Memory

Store and retrieve observations using hybrid search that combines:

• Vector similarity (embeddings) - finds conceptually related memories
• Full-text search (BM25) - matches exact keywords
• Temporal decay - recent memories rank higher
• Failure boost - past failures surface prominently to prevent repeating mistakes

Rules Engine

Create guardrails that are matched semantically against actions:

Trigger: "adding API endpoint"
→ Must do: ["Add rate limiting", "Write integration tests"]
→ Must not: ["Skip authentication"]
→ Ask first: ["Is this a breaking change?"]

Code Analysis

Parse TypeScript/JavaScript files with tree-sitter to extract:

• Classes, methods, and functions
• Interfaces and type aliases
• Import statements
• JSDoc documentation

Link memories to specific code entities for contextual recall.

---

Installation

Prerequisites

• Bun v1.0 or higher
• macOS: SQLite with extension support (via Homebrew: brew install sqlite)
• Linux: Works out of the box

Install from npm

bun install -g code-recall

---

Quick Start

1. Add to Claude Code

claude mcp add code-recall -- bunx code-recall

2. Restart Claude Code

The server starts automatically when you open Claude Code.

3. Start Using Memory

Once connected, Claude can store observations, search memories, check rules, and more using the MCP tools below.

Configuration with Other MCP Clients

Add to your MCP client configuration:

{
  "mcpServers": {
    "code-recall": {
      "command": "bunx",
      "args": ["code-recall"]
    }
  }
}

---

MCP Tools

code-recall provides 8 tools that AI agents can use:

store_observation

Store a new observation in memory with automatic conflict detection.

Parameter	Type	Description
category	decision | pattern | warning | learning	Type of observation
content	string	The main content
rationale	string?	Why this decision was made
tags	string[]?	Tags for categorization
file_path	string?	Associated file path

{
  "category": "decision",
  "content": "Use JWT for authentication",
  "rationale": "Stateless auth enables horizontal scaling",
  "tags": ["auth", "architecture"]
}

search_memory

Search memories using semantic similarity.

Parameter	Type	Description
query	string	Search query
limit	number?	Max results (default: 10)
category	string?	Filter by category
file_path	string?	Filter by file path

get_briefing

Get a session start briefing with stats, warnings, and failed approaches.

Parameter	Type	Description
focus_areas	string[]?	Topics to pre-fetch context for

set_rule

Create a new rule/guardrail with semantic trigger matching.

Parameter	Type	Description
trigger	string	Action pattern that triggers this rule
must_do	string[]?	Required actions
must_not	string[]?	Forbidden actions
ask_first	string[]?	Questions to consider

check_rules

Check which rules apply to an action.

Parameter	Type	Description
action	string	The action you're about to take

record_outcome

Record whether a decision worked or failed.

Parameter	Type	Description
memory_id	number	ID of the memory
outcome	string	Description of what happened
worked	boolean	Whether it was successful

list_rules

List all active rules. No parameters.

analyze_structure

Analyze a source file and extract its code structure.

Parameter	Type	Description
file_path	string	Path to the file
include_types	string[]?	Filter entity types

---

Recommended Workflow

┌─────────────────────────────────────────────────────────┐
│                    SESSION START                         │
│                         │                                │
│                         ▼                                │
│               get_briefing(focus_areas)                  │
│                         │                                │
└─────────────────────────┼───────────────────────────────┘
                          │
┌─────────────────────────┼───────────────────────────────┐
│                  BEFORE CHANGES                          │
│                         │                                │
│          ┌──────────────┴──────────────┐                │
│          ▼                              ▼                │
│   check_rules(action)          search_memory(query)     │
│                                                          │
└─────────────────────────────────────────────────────────┘
                          │
┌─────────────────────────┼───────────────────────────────┐
│                AFTER DECISIONS                           │
│                         │                                │
│                         ▼                                │
│        store_observation(category, content)              │
│                                                          │
└─────────────────────────────────────────────────────────┘
                          │
┌─────────────────────────┼───────────────────────────────┐
│              AFTER IMPLEMENTATION                        │
│                         │                                │
│                         ▼                                │
│         record_outcome(memory_id, worked)                │
│                                                          │
└─────────────────────────────────────────────────────────┘

---

Best Practices

Claude Code Skill

For optimal integration with Claude Code, add our Skill to your project. Skills teach Claude when and how to use code-recall automatically.

Install the Skill:

# From your project root
mkdir -p .claude/skills/code-recall
curl -o .claude/skills/code-recall/SKILL.md \
  https://raw.githubusercontent.com/AbianS/code-recall/main/.claude/skills/code-recall/SKILL.md

Or create .claude/skills/code-recall/SKILL.md manually with our skill template.

What the Skill Does

Once installed, Claude will automatically:

• Session start: Call get_briefing to load context and warnings
• Before changes: Check search_memory and check_rules for relevant past decisions
• After decisions: Store important choices with store_observation
• After implementation: Record outcomes with record_outcome

This creates a feedback loop where Claude learns from past successes and failures in your project.

---

Architecture

code-recall/
├── src/
│   ├── index.ts              # Entry point
│   ├── server.ts             # MCP server and tools
│   ├── database/
│   │   ├── index.ts          # DatabaseManager (SQLite + sqlite-vec)
│   │   └── schema.ts         # Database schema
│   ├── memory/
│   │   ├── index.ts          # MemoryManager
│   │   ├── embeddings.ts     # Local embeddings (@xenova/transformers)
│   │   └── search.ts         # Hybrid search implementation
│   ├── rules/
│   │   └── index.ts          # RulesEngine with semantic matching
│   └── code/
│       ├── index.ts          # Code analysis coordinator
│       ├── parser.ts         # tree-sitter WASM parser
│       └── extractors/       # Language-specific extractors
├── tests/                    # Comprehensive test suite
└── .code-recall/             # Data directory (auto-created)
    └── memory.db             # SQLite database

---

Technical Stack

Component	Technology
Runtime	Bun
Database	SQLite + sqlite-vec
Embeddings	@xenova/transformers (all-MiniLM-L6-v2, 384d)
Full-text Search	SQLite FTS5
Code Parsing	web-tree-sitter
Protocol	MCP (stdio transport)

Search Algorithm

The hybrid search combines multiple signals:

Signal	Weight	Description
Vector similarity	50%	Cosine similarity of embeddings
Full-text score	30%	BM25 ranking
Recency	15%	Exponential time decay
Failure boost	5%	Failed decisions rank higher

---

Development

# Run in development mode (with watch)
bun run dev

# Run tests
bun test

# Run specific test file
bun test tests/memory/search.test.ts

Test Coverage

The project includes 210+ tests covering:

• Database operations and vector search
• Embedding generation and similarity
• Hybrid search algorithm
• Rules engine semantic matching
• Code analysis and extraction
• MCP server tools

---

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

License

MIT License - see LICENSE for details.

---

with 💖 by AbianS