---

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.

$3

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

$3

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

$3

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?"]
`

$3

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

$3

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

$3

`bash
bun install -g code-recall
`

---

Quick Start

$3

`bash
claude mcp add code-recall -- bunx code-recall
`

$3

The server starts automatically when you open Claude Code.

$3

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

$3

Add to your MCP client configuration:

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

---

MCP Tools

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

$3

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 |

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

$3

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 |

$3

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

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

$3

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 |

$3

Check which rules apply to an action.

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

$3

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 |

$3

List all active rules. No parameters.

$3

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

$3

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:

`bash


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.

$3

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

$3

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

`bash


Run in development mode (with watch)

bun run dev

Run tests

bun test

Run specific test file

bun test tests/memory/search.test.ts
`

$3

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