Metadata-Version: 2.4
Name: memotrail
Version: 0.1.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/melihhopa/memotrail
Project-URL: Issues, https://github.com/melihhopa/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: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5.0; extra == 'dev'
Description-Content-Type: text/markdown

# 🔍 MemoTrail

**Every AI coding conversation you've ever had — searchable and remembered.**

MemoTrail is a persistent memory layer for AI coding assistants. It automatically records your sessions, indexes them semantically, and surfaces the most relevant past context in every new session.

> *"Why did we switch from Postgres to Redis 3 months ago?"*
> → MemoTrail finds the exact conversation where you decided that.

## The Problem

Every time you start a new Claude Code session, it's a blank slate. Your AI doesn't remember that you spent 3 hours yesterday debugging that auth flow, or that you decided to use Redis instead of Memcached, or that you tried approach X and it failed.

**You repeat yourself. Every. Single. Day.**

## The Solution

MemoTrail runs as an MCP server that gives your AI coding assistant a real memory:

- 🔍 **Search past conversations** — "What did we discuss about authentication?"
- 🧠 **Automatic indexing** — Every session is recorded and searchable
- 📝 **Decision tracking** — Important choices are preserved
- 🔒 **100% local** — Your data never leaves your machine
- ⚡ **5 min setup** — One install, one command

## Quick Start

```bash
# Install
pip install memotrail

# Index your existing Claude Code history
memotrail index

# Add to Claude Code
claude mcp add memotrail -- memotrail serve
```

That's it. Start a new Claude Code session and ask:
> "What did we work on last week?"

## How It Works

```
You code with Claude Code
        ↓
MemoTrail records the conversation
        ↓
Messages are chunked and embedded
        ↓
Stored locally (ChromaDB + SQLite)
        ↓
    Next session...
        ↓
Claude Code calls MemoTrail tools
        ↓
Relevant past context surfaces automatically
```

## Available Tools

Once connected, Claude Code can use these tools:

| Tool | What it does |
|------|-------------|
| `search_chats` | Search past conversations semantically |
| `get_decisions` | List recorded architectural decisions |
| `get_recent_sessions` | See what you worked on recently |
| `get_session_detail` | Deep dive into a specific session |
| `save_memory` | Manually save important facts |
| `memory_stats` | See how much is indexed |

## CLI Commands

```bash
# Index existing Claude Code history
memotrail index

# Search from terminal
memotrail search "redis caching decision"

# View stats
memotrail stats

# Run MCP server (usually called by Claude Code)
memotrail serve
```

## Architecture

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

Everything runs locally. No cloud, no accounts, no API keys needed.

- **Embedding model**: `all-MiniLM-L6-v2` (~80MB, runs on CPU)
- **Vector DB**: ChromaDB (persistent, local)
- **Metadata**: SQLite (single file)

## Roadmap

- [x] Claude Code session indexing
- [x] Semantic search across conversations
- [x] MCP server with 6 tools
- [x] CLI for indexing and searching
- [ ] Automatic decision extraction
- [ ] Session summarization
- [ ] Cursor collector
- [ ] Copilot collector
- [ ] VS Code extension
- [ ] Cloud sync (Pro)
- [ ] Team memory (Team)

## Development

```bash
# Clone
git clone https://github.com/melihhopa/memotrail.git
cd memotrail

# Install in dev mode
pip install -e ".[dev]"

# Run tests
pytest

# Lint
ruff check src/
```

## Contributing

Contributions welcome! See [CONTRIBUTING.md](docs/CONTRIBUTING.md) for guidelines.

Good first issues:
- [ ] Add Cursor session collector
- [ ] Add Copilot session collector
- [ ] Improve chunking strategy
- [ ] Add BM25 keyword search alongside semantic search

## License

MIT — see [LICENSE](LICENSE)

---

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