Agent Genesis

🔍 Semantic search across your Claude Code conversation history

Agent Genesis indexes and searches your Claude Code and Claude.ai/Desktop conversations, making it easy to find past discussions, decisions, and solutions.

🔒 Privacy First: Runs 100% locally. No API keys required. Your conversations never leave your machine.

---

What Does It Do?

Ask questions like:

• "Find my conversations about authentication"
• "When did I discuss database optimization?"
• "What was that solution for the API rate limiting issue?"

Agent Genesis finds relevant conversations using semantic search (meaning-based, not just keyword matching).

---

Table of Contents

• Prerequisites
• Quick Start
• Stopping the Service
• Importing Claude.ai Data
• Searching Your Conversations
• MCP Integration
• Troubleshooting
• How It Compares
• Configuration Reference
• Contributing

---

Prerequisites

Before you start, you need:

• Docker (version 20.10+) - Install Docker
• 6GB+ RAM available for Docker (required for the local embedding model)
• Claude Code conversations in your projects folder (created automatically when you use Claude Code)

Verify Docker is installed:

docker --version
# Should output: Docker version 20.10.x or higher

Find your Claude Code projects path:

OS	Path
Linux	~/.claude/projects/
macOS	~/.claude/projects/
Windows	C:\Users\YourName\.claude\projects\
Windows (WSL)	/home/youruser/.claude/projects/

---

Quick Start

Step 1: Clone the Repository

git clone https://github.com/Platano78/agent-genesis.git
cd agent-genesis

Step 2: Create Your Configuration

cp .env.example .env
cp docker-compose.template.yml docker-compose.yml

Step 3: Set Your Claude Code Path

Open .env in any text editor and set your Claude Code projects path:

Linux/macOS:

CLAUDE_PROJECTS_PATH=/home/youruser/.claude/projects

Windows (use forward slashes):

CLAUDE_PROJECTS_PATH=C:/Users/YourName/.claude/projects

Verify your path exists:

# Linux/macOS
ls ~/.claude/projects/

# Windows (PowerShell)
dir $env:USERPROFILE\.claude\projects

You should see folders with names like -home-user-project-myapp.

Step 4: Start the Service

docker-compose up -d

Wait about 30 seconds for startup, then verify it's running:

curl http://localhost:8080/health
# Should return: {"status": "OK", ...}

Windows (PowerShell):

Invoke-RestMethod http://localhost:8080/health

Step 5: Index Your Conversations

curl -X POST http://localhost:8080/index/trigger

This scans your Claude Code conversations and indexes them. First run may take 1-5 minutes depending on history size.

Step 6: Search!

curl -X POST http://localhost:8080/search \
  -H "Content-Type: application/json" \
  -d '{"query": "authentication", "n_results": 5}'

Example output:

{
  "query": "authentication",
  "results_count": 3,
  "results": [
    {
      "content": "Let me help you implement JWT authentication...",
      "project": "my-webapp",
      "score": 0.89
    },
    {
      "content": "For OAuth2, you'll need to set up...",
      "project": "api-server",
      "score": 0.76
    }
  ]
}

🎉 Done! Your Claude Code conversations are now searchable.

---

Stopping the Service

When you're done, stop the service to free up resources:

# Stop the containers
docker-compose down

# To restart later
docker-compose up -d

Note: Your indexed data is preserved. You don't need to re-index after restarting.

---

Importing Claude.ai / Claude Desktop Data

⚠️ Important: Claude.ai and Claude Desktop store conversations in the cloud, not on your computer. You must request a data export from Anthropic.

Step 1: Request Your Data

1. Go to claude.ai
2. Click your profile → Settings → Account
3. Request a data export
4. Wait for the email (can take 24-48 hours)
5. Download the ZIP file

Step 2: Import the ZIP

The indexer automatically detects data-*.zip files in the exports volume. Copy your ZIP into the container's exports directory, then trigger indexing:

# Copy the ZIP into the container's exports volume
docker cp /path/to/your/data-export.zip agent-genesis:/app/data/exports/

# Trigger indexing (picks up the new export automatically)
curl -X POST http://localhost:8080/index/trigger

Step 3: Verify

curl http://localhost:8080/stats

You should see counts in both alpha (Claude Code) and beta (Claude.ai) collections.

---

Searching Your Conversations

Basic Search

curl -X POST http://localhost:8080/search \
  -H "Content-Type: application/json" \
  -d '{"query": "how to fix the login bug", "n_results": 10}'

Search Only Claude Code

curl -X POST http://localhost:8080/search \
  -H "Content-Type: application/json" \
  -d '{"query": "database", "collections": ["alpha"]}'

Search Only Claude.ai

curl -X POST http://localhost:8080/search \
  -H "Content-Type: application/json" \
  -d '{"query": "project planning", "collections": ["beta"]}'

Filter by Project

curl -X POST http://localhost:8080/search \
  -H "Content-Type: application/json" \
  -d '{"query": "API design", "project_filter": "my-project"}'

---

MCP Integration (Optional)

Search your conversations directly from Claude Code using the MCP protocol.

How it works: The MCP server runs on your host machine and acts as a bridge to the Agent Genesis API running in Docker.

Step 1: Install the MCP Server

Run this on your host machine (not inside Docker):

pip install agent-genesis-mcp

📦 View on PyPI

Step 2: Configure Claude Code

Add to your ~/.claude.json:

{
  "mcpServers": {
    "agent-genesis": {
      "command": "agent-genesis-mcp",
      "args": []
    }
  }
}

Step 3: Restart Claude Code

Restart Claude Code to load the new MCP server.

Step 4: Use It

Ask Claude Code:

"Search my conversation history for discussions about authentication"

Claude will use the search_conversations tool automatically.

Available MCP Tools

Tool	Description
search_conversations	Search your conversation history
get_api_stats	See indexed conversation counts
check_api_health	Check if API is running
index_conversations	Trigger re-indexing
manage_scheduler	Set up automatic re-indexing

---

Troubleshooting

Service won't start

# Check container status
docker-compose ps

# View logs for errors
docker-compose logs agent-genesis

"Connection refused" when calling API

1. Wait 30 seconds after docker-compose up -d
2. Check if container is running: docker-compose ps
3. Check logs: docker-compose logs agent-genesis

Port 8080 already in use

Edit docker-compose.yml and change the port:

ports:
  - "8081:8080"  # Change 8081 to any free port

Then restart: docker-compose down && docker-compose up -d

Search returns no results

1. Check if data is indexed:

   curl http://localhost:8080/stats
   # Should show count > 0
   

2. If count is 0, trigger indexing:

   curl -X POST http://localhost:8080/index/trigger
   

3. Verify your .env path is correct:

   ls ~/.claude/projects/
   # Should show folders
   

Container runs out of memory

The service needs ~4-6GB RAM for the embedding model. Increase Docker memory:

1. Edit docker-compose.yml:

   mem_limit: 8g
   

2. Restart: docker-compose down && docker-compose up -d

ZIP import fails

• Ensure you're using an official Anthropic data export
• The ZIP must contain conversations.json
• Check the import output for specific errors

MCP server not connecting

1. Verify Docker container is running: curl http://localhost:8080/health
2. Verify MCP is installed: pip show agent-genesis-mcp
3. Check Claude Code logs for MCP errors

---

How It Compares

Feature	Agent Genesis	episodic-memory	claude-mem
Deployment	Docker container	Claude Code plugin	Claude Code plugin
Claude Code	✅	✅	✅
Claude.ai/Desktop	✅ ZIP import	❌	❌
REST API	✅	❌	❌
MCP Server	✅	✅	✅
100% Local	✅	✅	✅

Choose Agent Genesis if you:

• Need a REST API for external integrations
• Want to search Claude.ai/Desktop history (only option with ZIP import)
• Prefer a standalone service over a Claude Code plugin

---

Configuration Reference

Environment Variables (.env)

Variable	Description	Default
CLAUDE_PROJECTS_PATH	Path to Claude Code projects	Required
API_PORT	Port for the API	8080
LOG_LEVEL	Logging level	INFO

API Endpoints

Endpoint	Method	Description
/health	GET	Health check (collection stats + disk usage)
/health/deep	GET	Deep health check with ChromaDB search validation
/live	GET	Liveness probe (no DB calls, always fast)
/ready	GET	Readiness probe (collection stats + disk usage)
/stats	GET	Conversation counts per collection
/search	POST	Search conversations
/index/trigger	POST	Trigger indexing
/index/status	GET	Poll current indexing job status (no_job, running, complete, failed)

Nightly sync script — optional Faulkner-DB integration

scripts/sync-and-index.sh rsyncs your Claude Code conversations to the remote host, triggers indexing, and optionally runs the Faulkner-DB relationship extractor after indexing completes. This chains together the sync + indexing + knowledge-graph update as a single nightly job.

Set these env vars (in a wrapper script, cron environment, or your scheduler's env section) to enable the extractor step:

Variable	Purpose	Example
GENESIS_REMOTE_HOST	SSH target where Agent Genesis runs	user@my-server
FAULKNER_REPO	Local path to faulkner-db checkout (needed for extractor venv)	~/project/faulkner-db
FAULKNER_LLM_ENDPOINT	OpenAI-compatible base URL for relationship classification	http://localhost:8081/v1
FALKORDB_HOST / FALKORDB_PORT / FALKORDB_PASSWORD / FALKORDB_GRAPH	FalkorDB connection for extractor	See faulkner-db docs

The extractor step is skipped gracefully if the faulkner-db venv or state file is missing, so the sync works fine without it. A 20-hour run-gate on reports/extraction_state.json mtime prevents re-running within the same day.

The script also rsyncs ~/.claude/docs/ to the remote host's QMD doc store (for session-handoff files and other persistent notes that should be searchable across sessions). Safe no-op if the directory doesn't exist.

---

Architecture

┌─────────────────────────────────────────────────────────────┐
│  Your Computer (everything runs locally)                    │
│                                                             │
│  ┌─────────────────┐    ┌───────────────────────────────┐    │
│  │  Claude Code    │    │  Agent Genesis (Docker)       │    │
│  │                 │    │                               │    │
│  │  ~/.claude/     │───▶│  ChromaDB + Local Embeddings  │    │
│  │  projects/      │    │  (bge-small model)            │    │
│  └─────────────────┘    │                               │    │
│                        │  ┌─────────────┐ ┌─────────────┐ │    │
│  ┌─────────────────┐    │  │ Alpha       │ │ Beta        │ │    │
│  │ MCP Server      │───▶│  │ Claude Code │ │ Claude.ai   │ │    │
│  │ (optional)      │    │  └─────────────┘ └─────────────┘ │    │
│  └─────────────────┘    └───────────────────────────────┘    │
│                                                             │
│  🔒 No data leaves your machine. No API keys needed.        │
└─────────────────────────────────────────────────────────────┘

---

Development

Run Without Docker

python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
python -m daemon.api_server

Run Tests

cd mcp-server
pip install -e ".[dev]"
pytest

---

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests
5. Submit a pull request

---

License

MIT License - see LICENSE

---

Changelog

v1.7.0 (2026-08-17)

• Redesign the ChromaDB worker circuit breaker. A long-running index batch could blow the RPC deadline and latch vector search off permanently — searches silently degraded to keyword-only behind an HTTP 200 and a healthy container. Replaced with a locked state machine (CLOSED → OPEN → RECOVERING → CLOSED) and a single permanent supervisor, so a degraded vector arm always has recovery scheduled
• Classify worker errors at the raise site: a malformed query (empty text, bad collection) no longer opens a backend-health breaker for everyone
• Bound every wait. _start_worker used a blocking readline() whose deadline was only checked between reads, so a worker that never signalled ready wedged the supervisor indefinitely and READY_TIMEOUT had no effect
• Never restart the worker on the request path; only the supervisor owns process lifecycle, and query admission fails fast rather than waiting out a recovery probe
• Stamp collections with an embedding-model manifest, and refuse to serve on mismatch. Two same-dimension indexes built by different models previously loaded without error and returned confidently-ranked noise. scripts/stamp_manifest.py migrates existing indexes
• Add GET /health/vector reporting breaker state, epoch, generation, consecutive failures and state_age_s, so a monitor can alert on vector death without restarting mid-index
• New env vars: RPC_TIMEOUT_QUERY / RPC_TIMEOUT_INDEX / RPC_TIMEOUT_PING, VECTOR_QUERY_LOCK_TIMEOUT, VECTOR_LIVENESS_POLL_S, VECTOR_PROBE_REQUIRED_COLLECTIONS
• 55 worker-protocol tests, up from 34

v1.6.0 (2026-08-17)

• Index nested subagent transcripts — enumeration was non-recursive, so files below the session level were never opened
• Index tool_use, tool_result and thinking blocks; previously only text blocks became searchable, so tool-driven decisions were invisible to search
• Fix two silent failures: an unreadable path aborted the whole indexing pass and was reported as success, and EMBEDDING_MODEL was overwritten before reaching the worker
• Add EMBEDDING_DEVICE, EMBEDDING_QUERY_PREFIX and UPSERT_BATCH_SIZE
• Weighted RRF fusion; equal weights measurably regressed recall

v1.3.0 (2026-04-08)

• MCP server updated to align package and runtime version metadata at 1.3.0
• Added MCP resources and prompts for MCP 2025-11-25 compliance
• Added scheduler management and manual indexing MCP tools to the documented tool surface
• Fixed MCP validation scripts to verify the current release dynamically instead of hard-coding stale versions
• Improved daemon import fallback so missing optional dependencies report the real error cause
• Removed stale Claude Desktop LevelDB setup references from the public setup flow
• Generalized sync tooling so the tracked script no longer contains personal infrastructure hooks

v1.2.0 (2025-01-02)

• Complete documentation rewrite
• Fixed: Removed incorrect LevelDB claims (Claude.ai uses cloud storage)
• Added: Windows path instructions
• Added: Privacy statement (100% local)
• Added: Troubleshooting section
• Added: Stopping the service instructions

v1.1.0 (2024-12-31)

• Increased container memory to 6GB
• Added health monitoring scripts
• Added automated backups

v1.0.0 (2024-11-02)

• Initial release