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

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

Go to claude.ai
Click your profile → Settings → Account
Request a data export
Wait for the email (can take 24-48 hours)
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

Wait 30 seconds after docker-compose up -d
Check if container is running: docker-compose ps
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

Check if data is indexed:

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

If count is 0, trigger indexing:

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

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:

Edit docker-compose.yml:
```
mem_limit: 8g
```
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

Verify Docker container is running: curl http://localhost:8080/health
Verify MCP is installed: pip show agent-genesis-mcp
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:

Fork the repository
Create a feature branch
Make your changes
Run tests
Submit a pull request

License

MIT License - see LICENSE

Changelog

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

Name		Name	Last commit message	Last commit date
Latest commit History 20 Commits
.github/workflows		.github/workflows
config		config
daemon		daemon
mcp-server		mcp-server
npm		npm
scripts		scripts
.env.example		.env.example
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.template.yml		docker-compose.template.yml
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation

Agent Genesis

What Does It Do?

Table of Contents

Prerequisites

Quick Start

Step 1: Clone the Repository

Step 2: Create Your Configuration

Step 3: Set Your Claude Code Path

Step 4: Start the Service

Step 5: Index Your Conversations

Step 6: Search!

Stopping the Service

Importing Claude.ai / Claude Desktop Data

Step 1: Request Your Data

Step 2: Import the ZIP

Step 3: Verify

Searching Your Conversations

Basic Search

Search Only Claude Code

Search Only Claude.ai

Filter by Project

MCP Integration (Optional)

Step 1: Install the MCP Server

Step 2: Configure Claude Code

Step 3: Restart Claude Code

Step 4: Use It

Available MCP Tools

Troubleshooting

Service won't start

"Connection refused" when calling API

Port 8080 already in use

Search returns no results

Container runs out of memory

ZIP import fails

MCP server not connecting

How It Compares

Configuration Reference

Environment Variables (.env)

API Endpoints

Nightly sync script — optional Faulkner-DB integration

Architecture

Development

Run Without Docker

Run Tests

Contributing

License

Changelog

v1.3.0 (2026-04-08)

v1.2.0 (2025-01-02)

v1.1.0 (2024-12-31)

v1.0.0 (2024-11-02)

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 12

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages