{"id":50508975,"url":"https://github.com/aaronlab/claude-memory","last_synced_at":"2026-06-02T18:32:50.608Z","repository":{"id":348159659,"uuid":"1196748497","full_name":"aaronlab/claude-memory","owner":"aaronlab","description":"Cross-session memory system for Claude Code","archived":false,"fork":false,"pushed_at":"2026-03-31T06:18:27.000Z","size":193,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-09T15:53:22.280Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/aaronlab.png","metadata":{"files":{"readme":"README.md","changelog":null,"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-31T02:13:37.000Z","updated_at":"2026-03-31T06:18:30.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/aaronlab/claude-memory","commit_stats":null,"previous_names":["zey413/claude-memory","aaronagent/claude-memory","aaronlab/claude-memory"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/aaronlab/claude-memory","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronlab%2Fclaude-memory","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronlab%2Fclaude-memory/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronlab%2Fclaude-memory/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronlab%2Fclaude-memory/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aaronlab","download_url":"https://codeload.github.com/aaronlab/claude-memory/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronlab%2Fclaude-memory/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33833277,"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-02T02:00:07.132Z","response_time":109,"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":[],"created_at":"2026-06-02T18:32:50.001Z","updated_at":"2026-06-02T18:32:50.601Z","avatar_url":"https://github.com/aaronlab.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# claude-memory\n\n[![PyPI](https://img.shields.io/pypi/v/claude-memory)](https://pypi.org/project/claude-memory/)\n[![Tests](https://img.shields.io/badge/tests-259%20passed-brightgreen)]()\n[![Python](https://img.shields.io/badge/python-3.10%2B-blue)]()\n[![License](https://img.shields.io/badge/license-MIT-green)]()\n\nCross-session memory system for Claude Code. Extract, index, and recall context across sessions.\n\n## Features\n\n### Core\n- **Automatic Memory Extraction** — rule-based parsing of Claude Code session logs (JSONL) into structured memories\n- **Full-Text Search** — SQLite FTS5 with BM25 ranking and Porter stemming\n- **CLAUDE.md Generation** — auto-generates project context files that Claude Code reads on session start\n\n### AI-Powered\n- **Semantic Search** — sentence-transformer embeddings for meaning-based recall\n- **Hybrid Search** — combines FTS5 keyword matching with semantic similarity for best results\n\n### Analysis\n- **Knowledge Graph** — visualize cross-project memory relationships and shared patterns\n- **Memory Consolidation** — dedup, importance scoring, and stale TODO archival\n- **Session Diff \u0026 Replay** — compare sessions or replay a session timeline event by event\n\n### Integration\n- **MCP Server** — Model Context Protocol server lets Claude query memories in real-time during sessions\n- **SessionEnd Hook** — auto-triggers extraction when Claude Code sessions end\n- **Watch Mode** — daemon that monitors for new sessions and auto-ingests\n\n### User Interface\n- **Web Dashboard** — full-featured browser UI with search, browse, graph, stats, timeline, and session views\n- **Rich Terminal** — color-coded tables, panels, and formatted output via the `rich` library\n- **23-Command CLI** — comprehensive command-line interface for every operation\n\n## Quick Start\n\n```bash\n# 1. Install\npip install claude-memory\n\n# 2. Ingest your Claude Code sessions\nclaude-memory ingest --all\n\n# 3. Search your memories\nclaude-memory search \"authentication\"\n```\n\nThat's it. Memories are extracted from your existing Claude Code session logs and indexed for instant recall.\n\n## Installation\n\n```bash\npip install claude-memory                    # Core (FTS5 search, CLI, Rich output)\npip install 'claude-memory[web]'             # + Web Dashboard (FastAPI)\npip install 'claude-memory[embeddings]'      # + Semantic search (sentence-transformers)\npip install 'claude-memory[mcp]'             # + MCP server\npip install 'claude-memory[web,embeddings]'  # Full install\n```\n\nOr install from source:\n\n```bash\ngit clone https://github.com/Zey413/claude-memory.git\ncd claude-memory\npip install -e \".[dev,web,embeddings,mcp]\"\n```\n\n## Web Dashboard\n\nLaunch with `claude-memory ui` (requires `pip install 'claude-memory[web]'`):\n\n```bash\nclaude-memory ui --open          # Opens browser to http://localhost:8765\n```\n\nThe dashboard provides six views:\n\n| View | Description |\n|------|-------------|\n| **Search** | Real-time keyword and semantic search across all memories |\n| **Browse** | Filter and explore memories by type, project, and tags |\n| **Graph** | Interactive knowledge graph of memory relationships |\n| **Stats** | System-wide statistics, memory type distribution, and project breakdown |\n| **Timeline** | Chronological event timeline for session replay |\n| **Sessions** | Session history with metadata and extraction summaries |\n\n## CLI Commands\n\nAll 23 commands available via `claude-memory \u003ccommand\u003e`:\n\n| Command | Description |\n|---------|-------------|\n| **Ingestion** | |\n| `ingest` | Extract memories from Claude Code session logs |\n| `watch` | Auto-ingest new sessions in daemon mode |\n| `install-hook` | Install SessionEnd hook for auto-extraction |\n| `uninstall-hook` | Remove the SessionEnd hook |\n| **Search \u0026 Browse** | |\n| `search` | Full-text, semantic (`--semantic`), or hybrid (`--hybrid`) search |\n| `list` | List memories with type/project/tag filters |\n| `top` | Show top memories ranked by importance score |\n| `sessions` | List processed session summaries |\n| `projects` | List all discovered projects with session data |\n| **Analysis** | |\n| `graph` | Analyze cross-project memory relationships (summary/dot/json) |\n| `shared-patterns` | Find patterns and decisions shared across projects |\n| `consolidate` | Dedup, score, and archive stale memories |\n| `diff` | Compare memories between two sessions |\n| `replay` | Replay a session timeline showing key events |\n| `stats` | Show system-wide memory statistics |\n| **Generation \u0026 Export** | |\n| `generate` | Generate CLAUDE.md project context from memories |\n| `export` | Export memories to JSON |\n| `import-data` | Import memories from a JSON file |\n| **AI \u0026 Embeddings** | |\n| `embed` | Generate sentence-transformer embeddings for all memories |\n| **Servers** | |\n| `serve` | Start MCP server for real-time memory access |\n| `ui` | Launch the web dashboard |\n| **Management** | |\n| `tag` | Add/remove/list memory tags |\n| `reset` | Reset the memory database (destructive) |\n\n### Global Options\n\n| Option | Description |\n|--------|-------------|\n| `--db PATH` | Custom database path |\n| `--json-output` | Machine-readable JSON output |\n| `-v, --verbose` | Enable debug logging |\n\n## Memory Types\n\n| Type | Description | Example |\n|------|-------------|---------|\n| `decision` | Architecture and design decisions | \"Use FastAPI for the REST API\" |\n| `pattern` | Code patterns and conventions | \"Modified 8 files in /tests\" |\n| `issue` | Bugs found, errors encountered | \"Import error in module X\" |\n| `solution` | How issues were resolved | \"Fixed by adding \\_\\_init\\_\\_.py\" |\n| `preference` | User preferences and style choices | \"Prefer pytest over unittest\" |\n| `context` | Project context, domain knowledge | \"Service uses PostgreSQL 15\" |\n| `todo` | Unfinished work, future plans | \"Add API rate limiting\" |\n| `learning` | New concepts, techniques discovered | \"FTS5 supports Porter stemming\" |\n\n## Architecture\n\n```\n                         ┌──────────────────────────────────────────────────┐\n                         │           Claude Code Runtime                    │\n                         │                                                  │\n                         │  Every session is recorded as a .jsonl file:     │\n                         │  ~/.claude/projects/\u003cPATH\u003e/\u003cSESSION_ID\u003e.jsonl    │\n                         │                                                  │\n                         │  Each line = one JSON message:                   │\n                         │    - user messages (prompts, preferences)        │\n                         │    - assistant messages (text + tool_use blocks) │\n                         │    - file-history-snapshot, queue-operation      │\n                         └──────────────────────┬───────────────────────────┘\n                                                │\n                                                │ SessionEnd hook / watch mode\n                                                │ `claude-memory ingest --latest`\n                                                ▼\n┌───────────────────────────────────────────────────────────────────────────────┐\n│                          claude-memory Pipeline                               │\n│                                                                               │\n│  ┌─────────────┐    ┌──────────────────────┐    ┌──────────────────────────┐  │\n│  │             │    │                      │    │                          │  │\n│  │  Parser     │───▶│  Rule-based          │───▶│  SQLite + FTS5          │  │\n│  │  (parser.py)│    │  Extractor           │    │  (db.py)                │  │\n│  │             │    │  (extractor.py)       │    │                          │  │\n│  │ JSONL ──▶   │    │                      │    │  memories table          │  │\n│  │ ParsedMsg   │    │  5 extraction rules: │    │  sessions table          │  │\n│  │             │    │  - Decisions          │    │  tags table              │  │\n│  └─────────────┘    │  - File patterns     │    │  memories_fts (FTS5)     │  │\n│                     │  - TODOs             │    │  embeddings (optional)   │  │\n│                     │  - Error/fix pairs   │    │                          │  │\n│                     │  - Preferences       │    │  BM25 ranking            │  │\n│                     └──────────────────────┘    │  Porter stemming         │  │\n│                                                 └────────────┬─────────────┘  │\n│                                                              │                │\n│         ┌────────────────────────────────────────────────────┼──────────┐     │\n│         │                    │                    │           │          │     │\n│         ▼                    ▼                    ▼           ▼          │     │\n│  ┌──────────────┐  ┌────────────────┐  ┌──────────────┐ ┌─────────┐   │     │\n│  │ CLAUDE.md    │  │ Web Dashboard  │  │ MCP Server   │ │  CLI    │   │     │\n│  │ Generator    │  │ (FastAPI)      │  │ (mcp_server) │ │ (click) │   │     │\n│  │              │  │                │  │              │ │         │   │     │\n│  │ Writes to:   │  │ 6 views:       │  │ 4 tools:     │ │ 23 cmds │   │     │\n│  │ memory/      │  │ search, browse │  │ search, list │ │         │   │     │\n│  │ context.md   │  │ graph, stats   │  │ stats,       │ │         │   │     │\n│  │              │  │ timeline,      │  │ context      │ │         │   │     │\n│  │              │  │ sessions       │  │              │ │         │   │     │\n│  └──────┬───────┘  └────────────────┘  └──────────────┘ └─────────┘   │     │\n│         │                                                              │     │\n│         ▼                                                              │     │\n│  ┌──────────────────────────────────────────────────────────────────┐  │     │\n│  │  Next Claude Code session auto-reads CLAUDE.md                  │  │     │\n│  │  → Context from past sessions is available immediately          │  │     │\n│  └──────────────────────────────────────────────────────────────────┘  │     │\n└───────────────────────────────────────────────────────────────────────────────┘\n```\n\n## How It Works — Extraction Principles\n\n### Data Source: Claude Code Session Logs\n\nClaude Code automatically saves every conversation to `~/.claude/projects/\u003cPATH\u003e/\u003cSESSION_ID\u003e.jsonl`. Each line is a JSON object representing one message in the conversation:\n\n```jsonl\n{\"type\":\"user\",\"message\":{\"role\":\"user\",\"content\":\"Let's build a REST API\"},\"timestamp\":\"...\",\"cwd\":\"/my/project\"}\n{\"type\":\"assistant\",\"message\":{\"role\":\"assistant\",\"content\":[{\"type\":\"text\",\"text\":\"I'll use FastAPI...\"},{\"type\":\"tool_use\",\"name\":\"Write\",\"input\":{\"file_path\":\"main.py\",\"content\":\"...\"}}]}}\n```\n\nThese files contain **everything** — every prompt you typed, every response Claude gave, every file read/written, every command executed.\n\n### Step 1: Parse (parser.py)\n\nThe parser reads each JSONL line and converts it into a structured `ParsedMessage`:\n\n```\nRaw JSONL line  ──▶  ParsedMessage\n                       ├── role: \"user\" | \"assistant\"\n                       ├── text_content: (XML tags stripped)\n                       ├── tool_uses: [ToolUse(name, input_data)]\n                       ├── timestamp, cwd, git_branch\n                       └── is_meta: (skip /clear, /model commands)\n```\n\nFrom assistant messages, it extracts **tool_use blocks** — these tell us exactly which files were created (`Write`), edited (`Edit`), read (`Read`), and what shell commands were run (`Bash`).\n\n### Step 2: Extract (extractor.py)\n\nFive rule-based extractors scan the parsed messages using **regex patterns and structural analysis** (no LLM calls needed):\n\n| Extractor | What it finds | How |\n|-----------|--------------|-----|\n| **Decisions** | Architecture/design choices | Regex: `\"let's use X\"`, `\"decided to X\"`, `\"going to implement X\"` |\n| **File Patterns** | Which files were modified together | Track `Write`/`Edit` tool_use blocks, group by directory |\n| **TODOs** | Unfinished work | `TaskCreate` tool uses + regex for `TODO`, `FIXME`, `need to` |\n| **Error/Fix Pairs** | Bugs and their solutions | Find `Bash` failures → look ahead 5 messages for resolution |\n| **Preferences** | User style choices | Regex on user messages: `\"I prefer\"`, `\"always use\"`, `\"don't use\"` |\n\n### Step 3: Store \u0026 Index (db.py)\n\nExtracted memories go into SQLite with **FTS5 full-text search**:\n\n```\nmemories table (id, session_id, project, type, title, content, confidence)\n    │\n    ├── memories_fts (FTS5 virtual table with Porter stemming + BM25 ranking)\n    ├── memory_tags (many-to-many junction table)\n    ├── sessions table (summary stats per session)\n    └── embeddings table (optional, for semantic search)\n```\n\n### Step 4: Generate (generator.py)\n\nThe generator aggregates memories into a `CLAUDE.md` file that Claude Code **automatically reads on session start**:\n\n```markdown\n# Project Memory — my-project\n\u003e Auto-generated by claude-memory\n\n## Key Decisions\n- Use Alembic for database migrations\n- ...\n\n## Active TODOs\n- [ ] Add rollback support\n- ...\n\n## Recent Sessions\n- 2026-03-30 (13h): Built memory system, 77 interactions\n- ...\n```\n\n## MCP Server\n\nClaude Code can query memories in real-time during a session:\n\n```bash\nclaude-memory serve\n```\n\nExposes 4 tools via the Model Context Protocol: `memory_search`, `memory_list`, `memory_stats`, `memory_context`.\n\nAdd to your Claude Code MCP config using the `claude-memory-mcp` entry point.\n\n## Development\n\n```bash\n# Install all dev dependencies\npip install -e \".[dev,web,embeddings,mcp]\"\n\n# Run tests\npytest\n\n# Run tests with coverage\npytest --cov=claude_memory\n\n# Lint\nruff check src/ tests/\n\n# Format\nruff format src/ tests/\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faaronlab%2Fclaude-memory","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faaronlab%2Fclaude-memory","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faaronlab%2Fclaude-memory/lists"}