Metadata-Version: 2.4
Name: memotrail
Version: 1.0.0
Summary: Persistent memory layer for AI coding assistants. Every conversation remembered, every decision searchable.
Project-URL: Homepage, https://memotrail.ai
Project-URL: Repository, https://github.com/HalilHopa-Datatent/memotrail
Project-URL: Issues, https://github.com/HalilHopa-Datatent/memotrail/issues
Author-email: Halil Hopa <hello@memotrail.ai>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,claude-code,coding-assistant,context-management,mcp,memory,persistent-memory,semantic-search
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Requires-Dist: chromadb>=0.5.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: sentence-transformers>=3.0.0
Requires-Dist: tiktoken>=0.7.0
Requires-Dist: watchdog>=4.0.0
Provides-Extra: dev
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5.0; extra == 'dev'
Provides-Extra: sync
Requires-Dist: boto3>=1.34; extra == 'sync'
Provides-Extra: web
Requires-Dist: fastapi>=0.110; extra == 'web'
Requires-Dist: jinja2>=3.1; extra == 'web'
Requires-Dist: python-multipart>=0.0.9; extra == 'web'
Requires-Dist: uvicorn>=0.29; extra == 'web'
Description-Content-Type: text/markdown

<div align="center">

# MemoTrail

**Your AI coding assistant forgets everything. MemoTrail fixes that.**

[🇨🇳 中文](docs/i18n/README.zh-CN.md) · [🇹🇼 繁體中文](docs/i18n/README.zh-TW.md) · [🇯🇵 日本語](docs/i18n/README.ja.md) · [🇵🇹 Português](docs/i18n/README.pt.md) · [🇰🇷 한국어](docs/i18n/README.ko.md) · [🇪🇸 Español](docs/i18n/README.es.md) · [🇩🇪 Deutsch](docs/i18n/README.de.md) · [🇫🇷 Français](docs/i18n/README.fr.md) · [🇮🇱 עברית](docs/i18n/README.he.md) · [🇸🇦 العربية](docs/i18n/README.ar.md) · [🇷🇺 Русский](docs/i18n/README.ru.md) · [🇵🇱 Polski](docs/i18n/README.pl.md) · [🇨🇿 Čeština](docs/i18n/README.cs.md) · [🇳🇱 Nederlands](docs/i18n/README.nl.md) · [🇹🇷 Türkçe](docs/i18n/README.tr.md) · [🇺🇦 Українська](docs/i18n/README.uk.md) · [🇻🇳 Tiếng Việt](docs/i18n/README.vi.md) · [🇮🇩 Indonesia](docs/i18n/README.id.md) · [🇹🇭 ไทย](docs/i18n/README.th.md) · [🇮🇳 हिन्दी](docs/i18n/README.hi.md) · [🇧🇩 বাংলা](docs/i18n/README.bn.md) · [🇵🇰 اردو](docs/i18n/README.ur.md) · [🇷🇴 Română](docs/i18n/README.ro.md) · [🇸🇪 Svenska](docs/i18n/README.sv.md) · [🇮🇹 Italiano](docs/i18n/README.it.md) · [🇬🇷 Ελληνικά](docs/i18n/README.el.md) · [🇭🇺 Magyar](docs/i18n/README.hu.md) · [🇫🇮 Suomi](docs/i18n/README.fi.md) · [🇩🇰 Dansk](docs/i18n/README.da.md) · [🇳🇴 Norsk](docs/i18n/README.no.md)

[![PyPI version](https://img.shields.io/pypi/v/memotrail?color=blue)](https://pypi.org/project/memotrail/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![GitHub stars](https://img.shields.io/github/stars/HalilHopa-Datatent/memotrail?style=social)](https://github.com/HalilHopa-Datatent/memotrail)

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

[Quick Start](#quick-start) · [Features](#whats-new-in-v100) · [Available Tools](#available-tools) · [Dashboard](#web-dashboard) · [REST API](#rest-api) · [Roadmap](#roadmap)

</div>

---

## 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.

```bash
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.

```bash
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.

```bash
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.

<details>
<summary><strong>Previous releases</strong></summary>

#### 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
</details>

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

```bash
# 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?"*

<div align="center">
<img src="demo.gif" alt="MemoTrail Demo" width="800">
<br>
<sub>Install &rarr; Connect &rarr; See stats &rarr; Search past sessions &rarr; Save memory &rarr; Duplicate &amp; contradiction detection</sub>
</div>

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

```bash
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.

```bash
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/`:

```bash
# 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:

```toml
# ~/.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

- [x] Claude Code session indexing
- [x] Semantic search across conversations
- [x] MCP server with 12 tools
- [x] CLI for indexing, searching, export/import
- [x] Auto-indexing on server startup
- [x] Automatic decision extraction
- [x] Session summarization
- [x] Cursor IDE collector
- [x] BM25 keyword search + hybrid search
- [x] Real-time file watching (watchdog)
- [x] Multiple chunking strategies (token, turn, recursive)
- [x] VS Code extension
- [x] Memory consolidation (dedup, update, contradiction detection)
- [x] Cross-encoder search reranking
- [x] Automatic context injection (token-budgeted)
- [x] Knowledge graph (entities + relations)
- [x] Web dashboard (FastAPI + HTMX + D3.js)
- [x] GitHub Copilot collector
- [x] Windsurf collector
- [x] Aider collector
- [x] Optional LLM summarization (Ollama/OpenAI/Anthropic)
- [x] REST API (`/api/v1/`)
- [x] Temporal fact tracking
- [x] Data export/import (JSON)
- [x] Encrypted cloud backup (S3)
- [x] Memory scopes (user/project/session)
- [x] 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:**
```bash
cd vscode-extension
npm install
npm run compile
# Then press F5 in VS Code to launch Extension Development Host
```

## Development

```bash
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](docs/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](LICENSE)

---

<div align="center">

**Built by [Halil Hopa](https://halilhopa.com)** · [memotrail.ai](https://memotrail.ai)

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

</div>
