{"id":50980771,"url":"https://github.com/nyxtoolsdev/claude-memory-manager","last_synced_at":"2026-06-19T14:01:18.860Z","repository":{"id":346660300,"uuid":"1190997863","full_name":"NyxToolsDev/claude-memory-manager","owner":"NyxToolsDev","description":"Cross-session memory for Claude Code — never lose context between sessions","archived":false,"fork":false,"pushed_at":"2026-03-25T18:10:00.000Z","size":57,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-26T02:31:59.963Z","etag":null,"topics":["ai","claude","claude-code","context","developer-tools","mcp","memory"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NyxToolsDev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-24T20:28:34.000Z","updated_at":"2026-03-25T18:10:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/NyxToolsDev/claude-memory-manager","commit_stats":null,"previous_names":["nyxtoolsdev/claude-memory-manager"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/NyxToolsDev/claude-memory-manager","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NyxToolsDev%2Fclaude-memory-manager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NyxToolsDev%2Fclaude-memory-manager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NyxToolsDev%2Fclaude-memory-manager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NyxToolsDev%2Fclaude-memory-manager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NyxToolsDev","download_url":"https://codeload.github.com/NyxToolsDev/claude-memory-manager/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NyxToolsDev%2Fclaude-memory-manager/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34534278,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-19T02:00:06.005Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","claude","claude-code","context","developer-tools","mcp","memory"],"created_at":"2026-06-19T14:00:35.485Z","updated_at":"2026-06-19T14:01:18.849Z","avatar_url":"https://github.com/NyxToolsDev.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Claude Memory Manager\n\n\u003c!-- mcp-name: io.github.NyxToolsDev/claude-memory-manager --\u003e\n\n**Cross-session memory for Claude Code** — never lose context between sessions.\n\nClaude Memory Manager automatically captures architectural decisions, code changes, bug fixes, and configuration choices from your Claude Code sessions, then intelligently retrieves relevant context when you start new sessions.\n\n## What It Does\n\nEvery time you use Claude Code, valuable context is created and lost when the session ends:\n- Which libraries you chose and why\n- Bug fixes and their root causes\n- Configuration decisions\n- File structure and naming conventions\n- Error resolutions\n\nClaude Memory Manager solves this by:\n1. **Parsing** your Claude Code session logs (JSONL files)\n2. **Extracting** meaningful memories with importance scoring\n3. **Embedding** memories for semantic search\n4. **Storing** everything in a local SQLite database with FTS5\n5. **Retrieving** relevant context via hybrid semantic + keyword search\n6. **Serving** context to Claude Desktop via MCP protocol\n\n## Installation\n\n```bash\npip install claude-memory-manager\n```\n\nFor local embeddings (no API key needed):\n```bash\npip install claude-memory-manager[local]\n```\n\nFor development:\n```bash\npip install claude-memory-manager[dev]\n```\n\n## Quick Start\n\n### 1. Initialize the Database\n\n```bash\nclaude-memory init\n```\n\nThis creates the SQLite database at `~/.claude-memory/memory.db` and saves a config file.\n\n### 2. Ingest Session Logs\n\n```bash\n# Ingest all sessions from the default path (~/.claude/projects/)\nclaude-memory ingest\n\n# Ingest from a specific path\nclaude-memory ingest /path/to/sessions\n\n# Watch for new sessions and auto-ingest\nclaude-memory ingest --watch\n```\n\n### 3. Search Memories\n\n```bash\n# Search across all memories\nclaude-memory search \"authentication setup\"\n\n# Filter by project\nclaude-memory search \"database schema\" --project /path/to/project\n\n# Filter by category\nclaude-memory search \"cors\" --category config\n```\n\n### 4. Generate Context Summary\n\n```bash\n# List all indexed projects\nclaude-memory context\n\n# Generate summary for a specific project\nclaude-memory context /path/to/project\n\n# With custom token limit\nclaude-memory context /path/to/project --max-tokens 3000\n```\n\n### 5. Connect to Claude Desktop (MCP)\n\nAdd to your Claude Desktop config (see [MCP Setup](#mcp-setup)):\n\n```json\n{\n  \"mcpServers\": {\n    \"claude-memory\": {\n      \"command\": \"claude-memory-mcp\",\n      \"args\": []\n    }\n  }\n}\n```\n\n## CLI Reference\n\n| Command | Description |\n|---------|-------------|\n| `claude-memory init` | Initialize the SQLite database |\n| `claude-memory ingest [PATH]` | Ingest session logs from path |\n| `claude-memory ingest --watch` | Watch and auto-ingest new sessions |\n| `claude-memory search \"query\"` | Hybrid semantic + keyword search |\n| `claude-memory context [PROJECT]` | Generate context summary |\n| `claude-memory list` | List all indexed sessions |\n| `claude-memory stats` | Database statistics |\n| `claude-memory prune --older-than 90d` | Remove old memories |\n| `claude-memory export` | Export memories as JSON |\n| `claude-memory serve` | Start MCP server mode |\n\n### Global Options\n\n| Option | Description |\n|--------|-------------|\n| `--config PATH` | Custom config file path |\n| `--verbose` / `-v` | Enable debug logging |\n| `--version` | Show version |\n\n### Search Options\n\n| Option | Description |\n|--------|-------------|\n| `--project` / `-p` | Filter by project path |\n| `--category` / `-c` | Filter by category |\n| `--limit` / `-n` | Max results (default: 5) |\n\n### Categories\n\nMemories are classified into these categories:\n- `decision` — Architectural and design decisions\n- `code_change` — Significant code modifications\n- `bug_fix` — Bug identification and resolution\n- `config` — Configuration and environment changes\n- `error_resolution` — Errors encountered and solved\n- `preference` — User preferences and conventions\n- `discussion` — General discussion summaries\n\n## MCP Setup\n\n### Claude Desktop\n\n1. Find your Claude Desktop config file:\n   - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`\n   - **Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n2. Add the memory server:\n\n```json\n{\n  \"mcpServers\": {\n    \"claude-memory\": {\n      \"command\": \"claude-memory-mcp\",\n      \"args\": []\n    }\n  }\n}\n```\n\n3. Restart Claude Desktop.\n\nSee `examples/claude-desktop-config.json` for a complete example.\n\n### MCP Tools\n\nOnce connected, Claude Desktop can use these tools:\n\n| Tool | Description |\n|------|-------------|\n| `memory_search` | Search memories by query with optional filters |\n| `memory_recall` | Get a formatted context summary for a project |\n| `memory_save` | Save a new memory directly |\n| `memory_stats` | Get database statistics |\n\n## Architecture\n\n```\nclaude-memory-manager/\n  src/claude_memory/\n    cli.py              # Click CLI commands\n    mcp_server.py       # MCP stdio server\n    config.py           # Configuration management\n    core/\n      extractor.py      # Memory extraction from conversations\n      embedder.py       # Embedding generation + caching\n      indexer.py         # Pipeline: parse -\u003e extract -\u003e embed -\u003e store\n      retriever.py      # Hybrid semantic + keyword search\n      summarizer.py     # Context summary generation\n    parsers/\n      jsonl_parser.py   # Claude Code session log parser\n      diff_parser.py    # Unified diff parser\n    storage/\n      database.py       # SQLite + FTS5 operations\n      models.py         # Pydantic data models\n      migrations.py     # Schema versioning\n    integrations/\n      anthropic_embeddings.py  # Voyage AI API\n      local_embeddings.py      # sentence-transformers\n    utils/\n      formatting.py     # CLI output formatting\n      license.py        # License validation\n```\n\n### Data Flow\n\n```\nSession Logs (.jsonl)\n        |\n  [JSONL Parser] -----\u003e ParsedSession\n        |\n  [Extractor] --------\u003e Memory objects (categorized, scored)\n        |\n  [Embedder] ----------\u003e Embeddings (bytes for SQLite BLOB)\n        |\n  [Indexer] -----------\u003e SQLite DB (with FTS5 index)\n        |\n  [Retriever] ---------\u003e Search results (hybrid ranked)\n        |\n  [Summarizer] --------\u003e Context summary (markdown)\n```\n\n## Configuration\n\nConfiguration is loaded from (in priority order):\n1. Environment variables\n2. Config file (`~/.claude-memory/config.json`)\n3. Defaults\n\n### Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `CLAUDE_SESSIONS_PATH` | Path to session logs | `~/.claude/projects` |\n| `CLAUDE_MEMORY_DB_PATH` | Database file path | `~/.claude-memory/memory.db` |\n| `CLAUDE_MEMORY_EMBEDDING_PROVIDER` | `anthropic`, `voyage`, or `local` | `local` |\n| `ANTHROPIC_API_KEY` | Anthropic API key | — |\n| `VOYAGE_API_KEY` | Voyage AI API key | — |\n| `CLAUDE_MEMORY_MAX_TOKENS` | Max tokens for context | `2000` |\n| `CLAUDE_MEMORY_LOG_LEVEL` | Log level | `INFO` |\n\n### Embedding Providers\n\n| Provider | Dimension | Requires |\n|----------|-----------|----------|\n| `voyage` | 1024 | `VOYAGE_API_KEY` |\n| `anthropic` | 1024 | `ANTHROPIC_API_KEY` |\n| `local` | 384 | `pip install claude-memory-manager[local]` |\n\nIf no provider is available, a stub provider is used (keyword search still works, but semantic search is disabled).\n\n## FAQ\n\n**Where are my memories stored?**\nIn a SQLite database at `~/.claude-memory/memory.db`. All data stays local.\n\n**Does this send my code to any API?**\nOnly if you configure the Voyage or Anthropic embedding provider. In that case, only memory text content (not full session logs) is sent to generate embeddings. Use `local` for fully offline operation.\n\n**How does deduplication work?**\nEach memory's content is hashed (SHA-256). If a memory with the same hash already exists, it is skipped during ingestion.\n\n**How does hybrid search work?**\nResults from cosine-similarity vector search (70% weight) are combined with SQLite FTS5 keyword search results (30% weight). Memories appearing in both get combined scores.\n\n**Can I export my memories?**\nYes: `claude-memory export \u003e memories.json` or `claude-memory export -o file.json`.\n\n**How do I prune old memories?**\n`claude-memory prune --older-than 90d` removes memories older than 90 days. Supports `d` (days), `w` (weeks), `m` (months), `y` (years).\n\n## Development\n\n```bash\n# Clone and install in development mode\ngit clone https://github.com/nyxtools/claude-memory-manager.git\ncd claude-memory-manager\npip install -e \".[dev]\"\n\n# Run tests\npytest\n\n# Type check\nmypy src/\n\n# Lint\nruff check src/ tests/\n```\n\n## License\n\nMIT License. Copyright (c) 2026 NyxTools.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnyxtoolsdev%2Fclaude-memory-manager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnyxtoolsdev%2Fclaude-memory-manager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnyxtoolsdev%2Fclaude-memory-manager/lists"}