memotrail 1.0.0

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 · Features · Available Tools · Dashboard · REST API · Roadmap

---

What's New in v1.0.0

Automatic Context Injection

Your AI no longer needs to search manually. MemoTrail assembles relevant past decisions, memories, and session summaries automatically within a token budget.

Knowledge Graph

Entities (libraries, frameworks, files, services) and their relationships are extracted from every conversation. Ask "What libraries does this project use?" and get structured answers.

Web Dashboard

A full visual interface for browsing sessions, searching conversations, managing memories, and exploring your knowledge graph — powered by FastAPI + HTMX + D3.js.

pip install memotrail[web]
memotrail dashboard
# Open http://127.0.0.1:8765

5 Platforms Supported

Index conversations from Claude Code, Cursor, GitHub Copilot, Windsurf, and Aider — all in one unified memory.

memotrail index --all    # Index all platforms at once

REST API

Full HTTP API at /api/v1/ for CI/CD integration, custom dashboards, and automation.

Temporal Tracking

Track how decisions evolve over time. "When did we switch from Flask to FastAPI? What was the reason?"

Data Export/Import

Backup and restore your entire memory. Move between machines seamlessly.

memotrail export backup.json
memotrail import backup.json

Memory Scopes

Save memories at three levels: user (global), project (project-specific), or session (temporary).

LLM Summarization

Optional high-quality summaries using Ollama (local), OpenAI, or Anthropic — dramatically better than rule-based extraction.

Schema Migrations

Safe, automatic database upgrades when you update MemoTrail. No data loss.

Previous releases

v0.4.0

• Memory consolidation (dedup, update, contradiction detection)
• Cross-encoder search reranking (optional)
• 108 tests

v0.3.1

• Smart auto-chunking strategies
• 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 AI coding 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	Auto-indexes sessions from 5 platforms + 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, decisions, entities, and relationships are automatically extracted
5. Store	Vectors go to ChromaDB, metadata + knowledge graph to SQLite
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	Relevant past context is assembled automatically within a token budget

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, Cursor, GitHub Copilot, Windsurf, and Aider.

Available Tools

Once connected, your AI gets 12 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 with scope (user/project/session) — auto-deduplicates
memory_stats	View indexing statistics and storage usage
get_project_context	Get curated context for a project: decisions + memories + summaries
get_auto_context	Given a query, retrieve semantically relevant past context
query_graph	Query the knowledge graph ("What libraries do we use?")
get_entity	Get entity details with all its relationships
get_fact_history	Track how a decision or memory evolved over time

CLI Commands

memotrail serve                             # Start MCP server
memotrail search "redis caching decision"   # Search from terminal
memotrail stats                             # View indexing stats
memotrail index                             # Index current platform
memotrail index --all                       # Index all platforms
memotrail index --source copilot            # Index specific platform
memotrail dashboard                         # Launch web dashboard
memotrail export backup.json                # Export all data
memotrail import backup.json                # Import data
memotrail migrate                           # Run database migrations

Web Dashboard

A browser-based interface for visual exploration of your AI coding memory.

pip install memotrail[web]
memotrail dashboard --port 8765

Page	What you see
Home	Total sessions, messages, decisions, memories at a glance
Sessions	Paginated list of all AI sessions with summaries
Session Detail	Full message history and decisions for any session
Search	Live search with instant results (HTMX)
Memories	View, add, and delete memory notes
Graph	Interactive D3.js knowledge graph visualization

REST API

When the dashboard is running, a full REST API is available at /api/v1/:

# Search
curl -X POST http://127.0.0.1:8765/api/v1/search \
  -H "Content-Type: application/json" \
  -d '{"query": "redis cache"}'

# Sessions
curl http://127.0.0.1:8765/api/v1/sessions?limit=10

# Decisions
curl http://127.0.0.1:8765/api/v1/decisions

# Memories
curl http://127.0.0.1:8765/api/v1/memories
curl -X POST http://127.0.0.1:8765/api/v1/memories \
  -d '{"content": "Always use type hints", "tags": ["convention"]}'

# Knowledge Graph
curl http://127.0.0.1:8765/api/v1/graph/entities?entity_type=library
curl http://127.0.0.1:8765/api/v1/graph/entity/fastapi

# Auto-assembled context
curl -X POST http://127.0.0.1:8765/api/v1/context \
  -d '{"query": "auth flow", "project": "myapp"}'

# Stats
curl http://127.0.0.1:8765/api/v1/stats

Architecture

~/.memotrail/
├── chroma/          # Vector embeddings (ChromaDB)
└── memotrail.db     # Session metadata + knowledge graph + fact history (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
Knowledge Graph	SQLite	Entities, relations, BFS traversal
Consolidation	Embedding similarity + regex	Dedup, update, contradiction detection
Temporal Tracking	SQLite	Decision/memory evolution history
Metadata	SQLite	Single-file database
LLM Summarization	Ollama / OpenAI / Anthropic	Optional, configurable
File Watching	watchdog	Real-time session detection
Web Dashboard	FastAPI + Jinja2 + HTMX + D3.js	Optional [web] extra
Protocol	MCP	Model Context Protocol

Supported Platforms

Platform	Status	Format
Claude Code	Supported	JSONL session files
Cursor IDE	Supported	state.vscdb (SQLite)
GitHub Copilot	Supported	state.vscdb (SQLite)
Windsurf	Supported	state.vscdb (SQLite)
Aider	Supported	.aider.chat.history.md

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.

Optional LLM Summarization

Enable higher-quality session summaries by connecting a local or cloud LLM:

# ~/.memotrail/config.toml
llm_summarizer_enabled = true
llm_summarizer_backend = "ollama"    # "ollama", "openai", or "anthropic"

Backend	Model	Requirement
Ollama	llama3.2 (default)	ollama pull llama3.2
OpenAI	gpt-4o-mini (default)	OPENAI_API_KEY env var
Anthropic	claude-haiku (default)	ANTHROPIC_API_KEY env var

Why MemoTrail?

	MemoTrail	CLAUDE.md / Rules files	Manual notes
Automatic	Yes — indexes on every session start	No — you write it	No
Searchable	Semantic + keyword search	AI reads it, but only what you wrote	Ctrl+F only
Scales	Thousands of sessions	Single file	Scattered files
Context-aware	Auto-assembles relevant context	Static rules	Manual lookup
Multi-platform	5 AI tools indexed together	Per-tool	Per-tool
Visual	Web dashboard + graph	None	None
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 12 tools
• CLI for indexing, searching, export/import
• Auto-indexing on server startup
• 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
• Automatic context injection (token-budgeted)
• Knowledge graph (entities + relations)
• Web dashboard (FastAPI + HTMX + D3.js)
• GitHub Copilot collector
• Windsurf collector
• Aider collector
• Optional LLM summarization (Ollama/OpenAI/Anthropic)
• REST API (/api/v1/)
• Temporal fact tracking
• Data export/import (JSON)
• Encrypted cloud backup (S3)
• Memory scopes (user/project/session)
• Schema migrations
• Team memory sharing
• Plugin system for custom collectors

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,web]"
pytest                    # 249 tests
ruff check src/

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

Good first issues:

• Add team memory sharing
• Add plugin system for custom collectors
• Add dashboard authentication
• Add memory importance scoring

License

MIT — see LICENSE

---

Built by Halil Hopa · memotrail.ai

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