claude-memory

claude-memory

Cross-machine memory system for Claude Code. Records every session as searchable markdown, syncs across machines via Git, and exposes full-text search, semantic search, session summarization, and a knowledge graph through an MCP server.

The Problem

Claude Code stores session transcripts and memory locally in ~/.claude/projects/. If you work on the same projects across multiple machines, each machine has its own isolated memory. Agents on Machine B can't recall what you discussed on Machine A.

What This Does

Machine A                        Machine B
┌──────────────┐                ┌──────────────┐
│ Claude Code  │                │ Claude Code  │
│  SessionEnd  │──capture──┐    │  SessionEnd  │──capture──┐
└──────────────┘           │    └──────────────┘           │
                           ▼                               ▼
                   ┌──────────────┐                ┌──────────────┐
                   │ sessions/    │                │ sessions/    │
                   │   project/   │                │   project/   │
                   │     date/    │                │     date/    │
                   │       id.md  │                │       id.md  │
                   └──────┬───────┘                └──────┬───────┘
                          │ git push                      │ git push
                          ▼                               ▼
                   ┌──────────────────────────────────────────┐
                   │         GitHub (private repo)            │
                   │  Markdown files = source of truth        │
                   └──────────────────────────────────────────┘
                          │ git pull (SessionStart)
                          ▼
                   ┌──────────────────────────────────────┐
                   │            MCP Server                │
                   │  ┌────────────┐  ┌────────────────┐  │
                   │  │ MiniSearch │  │ Transformers.js │  │
                   │  │  (FTS)     │  │ (vectors)       │  │
                   │  └────────────┘  └────────────────┘  │
                   │  ┌────────────┐  ┌────────────────┐  │
                   │  │ Summaries  │  │ Knowledge      │  │
                   │  │ (digests)  │  │ Graph          │  │
                   │  └────────────┘  └────────────────┘  │
                   └──────────────────────────────────────┘

On every session end: the JSONL transcript is converted to clean markdown, committed, and pushed to GitHub.

On every session start: git pulls the latest sessions from all machines and rebuilds the search index.

During any session: agents can search memory (keyword or semantic), summarize past sessions, and build a knowledge graph of concepts, tools, and patterns across all projects.

Quick Start

One-liner install

git clone https://github.com/kltng/claude-memory.git ~/codebases/claude-memory
cd ~/codebases/claude-memory
./install.sh

The installer:

1. Installs npm dependencies
2. Imports all existing sessions from ~/.claude/projects/ into the memory repo
3. Builds the full-text search index
4. Adds SessionStart and SessionEnd hooks to ~/.claude/settings.json
5. Registers the MCP server in ~/.claude.json
6. Is idempotent — safe to run multiple times

After installation, restart Claude Code for changes to take effect.

On a second machine

git clone https://github.com/kltng/claude-memory.git ~/codebases/claude-memory
cd ~/codebases/claude-memory
./install.sh

Same command. The installer detects the existing repo, imports any local sessions not already present, commits and pushes them, and sets up hooks + MCP server.

Agent-assisted install

Tell Claude Code on any machine:

"Help me install this memory system: https://github.com/kltng/claude-memory — clone it and run ./install.sh"

Custom install location

./install.sh --dir /path/to/claude-memory

How It Works

Session Capture

When a Claude Code session ends, the SessionEnd hook fires:

1. hooks/session-end.sh receives hook input (JSON via stdin) containing transcript_path, session_id, and cwd
2. src/capture.ts reads the .jsonl transcript, parses each message, strips system tags, and converts to clean markdown
3. The markdown is saved to sessions/<project>/<date>/<session-id>.md
4. Changes are committed and pushed to the remote

The resulting markdown looks like:

# Session: abc123-def456

| Field | Value |
|-------|-------|
| **Project** | my-app |
| **Date** | 2026-03-09 |
| **Branch** | main |
| **Messages** | 42 |

---

## User <sub>14:30:05</sub>

How do I fix the database connection timeout?

## Assistant <sub>14:30:12</sub>

The timeout is caused by...

**Tool: Bash**
` ``
{"command":"grep -r 'timeout' src/db/","description":"Search for timeout config"}
` ``

Git Sync

• SessionStart hook: git pull --rebase --autostash to get sessions from other machines, then rebuilds the search index if new markdown was pulled
• SessionEnd hook: git add sessions/ summaries/ → git commit → git push
• Conflict strategy: Session files have unique UUIDs, so they never conflict. Only summaries could theoretically conflict, handled by git merge.

Search

Full-Text Search (MiniSearch)

• Markdown files are chunked by headings (## / ###)
• Each chunk is indexed with project name, date, session ID, and heading
• Fuzzy matching and prefix search enabled
• Search index stored locally as search-index.json (gitignored — rebuilt from markdown)

Semantic / Vector Search (Transformers.js)

• Uses all-MiniLM-L6-v2 for 384-dimensional embeddings
• Runs entirely locally via @huggingface/transformers — no external APIs or Ollama required
• First run downloads the model (~80MB), cached locally afterwards
• Hybrid search combines vector + keyword results using Reciprocal Rank Fusion (RRF)
• Vector index stored locally as vector-index.json (gitignored — rebuilt from markdown)

Session Summarization

Agents can summarize sessions into concise digests:

1. Call get_unsummarized_sessions to find sessions needing summaries
2. Read each session with get_session
3. Call save_session_summary with a title, summary, tags, and extracted entities/relations

Summaries are stored at summaries/<project>/digests/<session-id>.md and automatically indexed for search. The save_session_summary tool can simultaneously populate the knowledge graph with extracted entities and relations.

Knowledge Graph

A lightweight entity–relation graph that tracks concepts, tools, patterns, and their connections across all projects:

• Entity types: project, file, concept, tool, library, pattern, error, person, service
• Relation types: uses, depends_on, implements, fixes, related_to, part_of, alternative_to, caused_by, learned_from, configured_with, deployed_to
• Provenance: every entity/relation tracks which sessions and projects it was mentioned in
• Queries: search entities, explore connections, find paths between concepts, identify hub entities
• Stored as knowledge-graph.json (git-tracked — shared across machines)

MCP Tools

The MCP server exposes 15 tools:

Search

| Tool | Description | |------|-------------| | search_memory | Full-text keyword search across all sessions and insights | | semantic_search | Vector similarity search, with hybrid mode (FTS + vectors via RRF). Falls back to FTS if vector index not built | | rebuild_index | Rebuild the full-text search index | | rebuild_vector_index | Rebuild the vector index (downloads model on first run) |

Sessions

| Tool | Description | |------|-------------| | list_sessions | List sessions filtered by project and/or date | | get_session | Retrieve full markdown transcript (truncated at 50K chars) | | save_insight | Save a curated insight to summaries/<project>/<topic>.md |

Summarization

| Tool | Description | |------|-------------| | get_unsummarized_sessions | List sessions that don't have a summary digest yet | | save_session_summary | Save a session summary with title, tags, and optional KG entities/relations | | list_summaries | List all summaries and insights across projects |

Knowledge Graph

| Tool | Description | |------|-------------| | kg_add | Add entities and relations (auto-creates missing entities, deduplicates by name) | | kg_search | Search entities by name, type, or project | | kg_query | Explore entity connections, find paths between entities, list hubs, or view stats | | kg_remove | Remove an entity (and its relations) or a specific relation |

Updating

To pull new features from the public template into your installed copy:

cd ~/codebases/claude-memory
./update.sh

This fetches upstream changes, merges them (keeping your session data, taking upstream code), reinstalls dependencies, rebuilds the search index, and pushes to your private repo.

Project Structure

claude-memory/
├── sessions/                    # Auto-captured transcripts (git tracked)
│   ├── my-app/
│   │   └── 2026-03-09/
│   │       └── abc123.md
│   └── other-project/
│       └── ...
├── summaries/                   # Curated insights + session digests (git tracked)
│   └── my-app/
│       ├── database-patterns.md
│       └── digests/
│           └── abc123.md
├── src/
│   ├── server.ts                # MCP server (15 tools)
│   ├── capture.ts               # JSONL → markdown converter
│   ├── search.ts                # MiniSearch wrapper (FTS)
│   ├── vector-search.ts         # Transformers.js embeddings + cosine similarity
│   ├── knowledge-graph.ts       # Entity–relation graph with BFS path finding
│   ├── rebuild-index.ts         # FTS index rebuild script
│   ├── rebuild-vector-index.ts  # Vector index rebuild script
│   ├── import-all.ts            # Bulk import from ~/.claude/projects/
│   ├── install-config.ts        # Installer config helper
│   ├── sync.ts                  # Git pull/push helper
│   └── __tests__/               # 81 tests
│       ├── capture.test.ts
│       ├── search.test.ts
│       ├── server.test.ts
│       └── knowledge-graph.test.ts
├── hooks/
│   ├── session-start.sh         # git pull + rebuild index
│   └── session-end.sh           # capture + git push
├── install.sh                   # Automated installer
├── update.sh                    # Pull upstream code updates
├── search-index.json            # FTS index (gitignored)
├── vector-index.json            # Vector index (gitignored)
├── knowledge-graph.json         # Knowledge graph (git tracked)
├── package.json
└── tsconfig.json

Configuration

Hooks (added to ~/.claude/settings.json)

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "~/codebases/claude-memory/hooks/session-start.sh",
            "timeout": 15,
            "async": true
          }
        ]
      }
    ],
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "~/codebases/claude-memory/hooks/session-end.sh",
            "timeout": 120,
            "async": true
          }
        ]
      }
    ]
  }
}

MCP Server (added to ~/.claude.json)

{
  "mcpServers": {
    "claude-memory": {
      "type": "stdio",
      "command": "npx",
      "args": ["--prefix", "~/codebases/claude-memory", "tsx", "~/codebases/claude-memory/src/server.ts"],
      "env": {
        "CLAUDE_MEMORY_ROOT": "~/codebases/claude-memory"
      }
    }
  }
}

Token Overhead

| Component | Tokens | When | |-----------|--------|------| | Tool definitions (15 tools) | ~2,000 | Every session (constant, deferred) | | search_memory result | ~300–500 | Per search call | | semantic_search result | ~400–800 | Per search call | | list_sessions result | ~200–1,000 | Per list call | | get_session result | ~500–12,500 | Per retrieval (capped) | | kg_query result | ~200–1,000 | Per query call | | save_* confirmations | ~50 | Per save call | | Hooks | 0 | Run outside context window |

Claude Code's MCP Tool Search defers tool loading, so the actual overhead is near-zero until a memory tool is invoked.

Requirements

• Claude Code (v2.1+)
• Node.js 18+
• Git
• A GitHub account (for cross-machine sync)

Development

# Run all tests (81 tests)
npm test

# Rebuild full-text search index
npx tsx src/rebuild-index.ts

# Rebuild vector search index (downloads model on first run)
npx tsx src/rebuild-vector-index.ts

# Import all local sessions
npx tsx src/import-all.ts

License

MIT