memotrail 0.4.1

Persistent memory layer for AI coding assistants. Every conversation remembered, every decision searchable.

MemoTrail

Your AI coding assistant forgets everything. MemoTrail fixes that.

🇨🇳 中文 · 🇹🇼 繁體中文 · 🇯🇵 日本語 · 🇵🇹 Português · 🇰🇷 한국어 · 🇪🇸 Español · 🇩🇪 Deutsch · 🇫🇷 Français · 🇮🇱 עברית · 🇸🇦 العربية · 🇷🇺 Русский · 🇵🇱 Polski · 🇨🇿 Čeština · 🇳🇱 Nederlands · 🇹🇷 Türkçe · 🇺🇦 Українська · 🇻🇳 Tiếng Việt · 🇮🇩 Indonesia · 🇹🇭 ไทย · 🇮🇳 हिन्दी · 🇧🇩 বাংলা · 🇵🇰 اردو · 🇷🇴 Română · 🇸🇪 Svenska · 🇮🇹 Italiano · 🇬🇷 Ελληνικά · 🇭🇺 Magyar · 🇫🇮 Suomi · 🇩🇰 Dansk · 🇳🇴 Norsk

A persistent memory layer for AI coding assistants. Every session recorded, every decision searchable, every context remembered.

Quick Start · How It Works · Available Tools · Roadmap

---

What's New in v0.4.0

• Memory consolidation — duplicate detection for memories and decisions using embedding similarity. Automatically decides: ADD (new info), UPDATE (richer version), DELETE (contradiction detected), or NOOP (duplicate skipped)
• Contradiction detection — regex-based patterns detect when new information replaces old ("switched from X to Y", "no longer using X") and automatically cleans up stale records
• Search reranking — optional cross-encoder reranking (cross-encoder/ms-marco-MiniLM-L-6-v2) for higher quality search results. Disabled by default, enable with reranker_enabled=True
• Smarter save_memory — now reports what happened: "saved", "updated", "replaced", or "already exists"
• 108 tests — comprehensive test coverage across all modules

Previous (v0.3.1)

• Smart auto-chunking — automatically picks the best chunking strategy per session
• Automatic session summarization and decision extraction
• BM25 keyword search + hybrid search (semantic + keyword with RRF)
• Cursor IDE support, real-time file watching, VS Code extension

The Problem

Every new Claude Code session starts from zero. Your AI doesn't remember yesterday's 3-hour debugging session, the architectural decisions you made last week, or the approaches that already failed.

Without MemoTrail:

You: "Let's use Redis for caching"
AI:  "Sure, let's set up Redis"
         ... 2 weeks later, new session ...
You: "Why are we using Redis?"
AI:  "I don't have context on that decision"

With MemoTrail:

You: "Why are we using Redis?"
AI:  "Based on session from Jan 15 — you evaluated Redis vs Memcached.
      Redis was chosen for its data structure support and persistence.
      The discussion is in session #42."

Quick Start

# 1. Install
pip install memotrail

# 2. Connect to Claude Code (current project)
claude mcp add memotrail -- memotrail serve

# Or connect globally (all projects)
claude mcp add -s user memotrail -- memotrail serve

That's it. MemoTrail automatically indexes your history on first launch. Start a new session and ask: "What did we work on last week?"

_{Install → Connect → See stats → Search past sessions → Save memory → Duplicate & contradiction detection}

How It Works

Step	What happens
1. Record	MemoTrail auto-indexes new sessions on startup + watches for new files in real-time
2. Chunk	Conversations are split using token, turn-based, or recursive strategies
3. Embed	Each chunk is embedded using all-MiniLM-L6-v2 (~80MB, runs on CPU)
4. Extract	Summaries and architectural decisions are automatically extracted
5. Store	Vectors go to ChromaDB, metadata to SQLite — all under ~/.memotrail/
6. Consolidate	Deduplicates memories and decisions — no stale or duplicate data
7. Search	Semantic + BM25 keyword search across your full history
8. Rerank	Optional cross-encoder reranking for higher precision results
9. Surface	The most relevant past context appears right when you need it

100% local — no cloud, no API keys, no data leaves your machine.

Project-aware — each project's conversations are stored separately. Search within a single project or across all projects at once.

Multi-platform — supports Claude Code and Cursor IDE, with more coming soon.

Available Tools

Once connected, Claude Code gets these MCP tools:

Tool	Description
search_chats	Semantic search across all past conversations
search_keyword	BM25 keyword search — great for exact terms, function names, error messages
get_decisions	Retrieve recorded architectural decisions (auto-extracted + manual)
get_recent_sessions	List recent coding sessions with AI-generated summaries
get_session_detail	Deep dive into a specific session's content
save_memory	Save facts or decisions — auto-deduplicates and detects contradictions
memory_stats	View indexing statistics and storage usage

CLI Commands

memotrail serve                          # Start MCP server (auto-indexes new sessions)
memotrail search "redis caching decision"  # Search from terminal
memotrail stats                          # View indexing stats
memotrail index                          # Manually re-index (optional)

Architecture

~/.memotrail/
├── chroma/          # Vector embeddings (ChromaDB)
└── memotrail.db     # Session metadata (SQLite)

Component	Technology	Details
Embeddings	all-MiniLM-L6-v2	~80MB, runs on CPU
Reranking	cross-encoder/ms-marco-MiniLM-L-6-v2	~80MB, optional, CPU
Vector DB	ChromaDB	Persistent, local storage
Keyword Search	BM25	Pure Python, no extra dependencies
Consolidation	Embedding similarity + regex	Dedup, update, contradiction detection
Metadata	SQLite	Single-file database
File Watching	watchdog	Real-time session detection
Protocol	MCP	Model Context Protocol

Supported Platforms

Platform	Status	Format
Claude Code	Supported	JSONL session files
Cursor IDE	Supported	state.vscdb (SQLite)
GitHub Copilot	Planned	—

Chunking Strategies

Strategy	Best for
auto (default)	Automatically picks the best strategy per session
token	General use — groups messages up to token limit
turn	Conversation-focused — groups user+assistant pairs
recursive	Long content — splits on paragraphs, sentences, words

Auto strategy rules: ≤20 messages → turn, avg ≥300 tokens/message → recursive, otherwise → token. No configuration needed.

Why MemoTrail?

	MemoTrail	CLAUDE.md / Rules files	Manual notes
Automatic	Yes — indexes on every session start	No — you write it	No
Searchable	Semantic search	AI reads it, but only what you wrote	Ctrl+F only
Scales	Thousands of sessions	Single file	Scattered files
Context-aware	Returns relevant context	Static rules	Manual lookup
Setup	5 minutes	Always maintained	Always maintained

MemoTrail doesn't replace CLAUDE.md — it complements it. Rules files are for instructions. MemoTrail is for memory.

Roadmap

• Claude Code session indexing
• Semantic search across conversations
• MCP server with 7 tools
• CLI for indexing and searching
• Auto-indexing on server startup (no manual memotrail index needed)
• Automatic decision extraction
• Session summarization
• Cursor IDE collector
• BM25 keyword search + hybrid search
• Real-time file watching (watchdog)
• Multiple chunking strategies (token, turn, recursive)
• VS Code extension
• Memory consolidation (dedup, update, contradiction detection)
• Cross-encoder search reranking (optional)
• Copilot collector
• Cloud sync (Pro)
• Team memory (Team)

VS Code Extension

MemoTrail includes a VS Code extension for direct IDE integration.

Commands available:

• MemoTrail: Search Conversations — semantic search
• MemoTrail: Keyword Search — BM25 keyword search
• MemoTrail: Recent Sessions — view session stats
• MemoTrail: Index Sessions Now — trigger manual indexing
• MemoTrail: Show Stats — display indexing statistics

Setup:

cd vscode-extension
npm install
npm run compile
# Then press F5 in VS Code to launch Extension Development Host

Development

git clone https://github.com/HalilHopa-Datatent/memotrail.git
cd memotrail
pip install -e ".[dev]"
pytest
ruff check src/

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

Good first issues:

• Add GitHub Copilot session collector
• Add Windsurf/Codeium session collector
• Add cloud sync option (opt-in)
• Add team memory sharing

License

MIT — see LICENSE

---

Built by Halil Hopa · memotrail.ai

If MemoTrail helps you, consider giving it a star on GitHub.