claude-memory: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

claude-memory — an MCP server (server.py + context_bridge/ package) that gives Claude Code persistent memory across terminal restarts and context-window compaction, targeted access to relevant claude.ai conversations, and bidirectional sync with claude.ai Projects.

Commands

# Install dependencies
pip install -r requirements.txt

# Run the server directly (smoke-test)
python3 server.py

# Test tools interactively
python3 -m mcp dev server.py

# Run all tests
pytest test_server.py tests/ -v

# Run project sync CLI
python -m context_bridge --auto

Core server is server.py. Project sync lives in context_bridge/ package. Tests in test_server.py (local storage) and tests/ (project sync).

Hard constraint — no LLM inference in server.py

server.py must never import anthropic or call any inference API. All summarisation and reasoning is performed by Claude Code itself (subscription), not programmatic API calls. The server is a dumb data layer: fetch, store, return raw content. Claude Code does the thinking.

Architecture

Three independent feature areas share server.py.

1. Local storage tools — no network, no Chrome required

Storage root: ~/.claude-memory/

~/.claude-memory/
├── sessions/    {project_name}_{sha1[:8]}_{YYYYMMDDTHHMMSSZ}_{id8}.json
├── images/      {image_id12}.{ext}  +  {image_id12}.json (metadata)
├── projects/    {project_key}.json  (conversation registry, includes project_path)
└── summaries/   {conversation_id}.json  (cached conversation summaries)

Private helpers (shared across tools):

• _storage(subdir) — mkdir + return Path under ~/.claude-memory/
• _project_key(path) — {dirname}_{sha1[:8]}, stable and filesystem-safe
• _load_registry(pk) / _save_registry(pk, reg) — read/write projects/{pk}.json
• _get_latest_checkpoint(project_path) — returns checkpoint dict or {"found": False}; used by both resume_session and get_latest_session_checkpoint
• _get_linked_conversations(project_key) — returns conversations list from registry; used by both resume_session and get_project_conversations
• _fetch_and_cache_summary(conv_id, refresh) — fetch from cache or API, always caches result; used by get_conversation_summary and link_conversation auto-note generation; raises RuntimeError on API failure