claude.ai Project
    ├── [manually added] Research notes, design docs
    ├── [cli] Status - repo-name.md     ← auto-pushed from CLI
    ├── [cli] TODOs - repo-name.md      ← pushed from CLI
    └── Project knowledge docs          ← readable from CLI

CLI (repos with <!-- claude-project: Name --> in CLAUDE.md)
    ├── reads Project knowledge docs
    └── pushes status/TODOs automatically

git clone https://github.com/AmmarJawad/claude-memory.git
cd claude-memory

pip install -r requirements.txt

{
  "mcpServers": {
    "claude-memory": {
      "type": "stdio",
      "command": "python3",
      "args": ["/path/to/claude-memory/server.py"]
    }
  }
}

{
  "mcpServers": {
    "claude-memory": {
      "command": "python3",
      "args": ["/path/to/claude-memory/server.py"]
    }
  }
}

resume_session("/path/to/project")
# → {
#     "checkpoint": { "summary": "...", "current_task": "...", ... },
#     "linked_conversations": [{ "conversation_id": "abc-123", "note": "auth design — JWT..." }]
#   }

get_conversation_summary("abc-123")  # cached after first fetch — no Chrome needed
get_conversation("abc-123")          # full content — last resort only

link_conversation("/path/to/project", "abc-123")
# auto-note: "Auth Design Session: How should we handle token refresh? ..."

## Session continuity (via claude-memory MCP)

**At the start of every session:**
Call `resume_session` with the project path. It returns both the latest
checkpoint and all linked conversations in a single call. Read the checkpoint
to restore context. Read the conversation notes — fetch a conversation only
if the note indicates the content is needed right now.

Fetch order (leanest to most expensive):
- Note alone — skip fetch if it answers your question
- `get_conversation_summary(id)` — cached, no Chrome required after first fetch
- `get_conversation(id)` — full content, last resort only

**During the session:**
Call `save_session_checkpoint` whenever a significant milestone is reached.
If a claude.ai conversation proves useful, call `link_conversation` with just
the conversation ID — the note is auto-generated.

**Before stopping work:**
Always call `save_session_checkpoint` with:
- `summary`: what was accomplished (specific files, features, fixes)
- `current_task`: anything in-progress or interrupted mid-task
- `key_files`: comma-separated paths of files created or modified
- `decisions_made`: architectural or design choices and their rationale
- `open_questions`: blockers or things to investigate next

Never call `list_conversations` to browse — use `resume_session` or
`get_project_conversations` instead. Only call `list_conversations` when
explicitly asked to discover a new conversation to link.

## Image / screenshot continuity (via claude-memory MCP)

**When any image or screenshot is shared:**
Immediately call `save_image` with:
- `source_path`: the file path (if the image came from a file)
- `description`: detailed description of everything visible — UI elements,
  error text, file paths, layout. This survives even if the file is lost.
- `tags`: relevant tags (e.g. "screenshot,bug,login-page")

Note the returned `image_id` and `stored_path`.

**After context compaction (if an image is no longer visible):**
Call `get_image(image_id)` to retrieve the stored path, then use the Read
tool on `stored_path` to re-embed the image.

## claude.ai Project sync (via claude-memory MCP)

**Setup:** Add `<!-- claude-project: Project Name -->` to this project's
CLAUDE.md to map it to a claude.ai Project.

**Push progress automatically:**
After significant milestones, call `push_session_summary` to push a
git-derived status summary to the Project. Use `push_todos` to share
the TODO list. Use `push_to_project` for custom content (design notes,
decisions, research summaries).

**Read Project knowledge:**
Call `list_project_docs` to see what's in the Project (including docs
added manually in claude.ai). Call `get_project_doc` to read specific
documents. This enables research done in claude.ai to flow back into CLI.

<!-- claude-project: My Project Name -->

# Push arbitrary content
push_to_project(content="# Design Notes\n\nWe chose approach B because...", doc_name="design-notes.md")

# Auto-generate and push status from git state
push_session_summary()
# → creates "[cli] Status - repo-name.md" with recent commits, branch, ahead count

# Push a TODO list
push_todos(todos=["[x] Implement auth", "Write tests", "Update docs"])
# → creates "[cli] TODOs - repo-name.md"

# List all Projects
list_projects()

# Browse Project knowledge docs
list_project_docs()  # uses project from CLAUDE.md
list_project_docs(project="My Project Name")  # or specify explicitly

# Read a specific doc
get_project_doc(doc_id="abc-123")

# hooks/post_push.sh — runs: python -m context_bridge.push --auto
# Configure as a Claude Code PostToolUse hook or git post-commit hook

~/.claude-memory/
├── sessions/    one JSON file per checkpoint, keyed by project path
├── images/      copied image files + JSON metadata, keyed by image ID
├── projects/    conversation registry, one JSON file per project
└── summaries/   cached conversation summaries, keyed by conversation ID

# Preview
cleanup_session_checkpoints("/path/to/project", keep_latest=10)
cleanup_images(older_than_days=30)
cleanup_summaries(older_than_days=90)

# Delete for real
cleanup_session_checkpoints("/path/to/project", keep_latest=10, dry_run=False)
cleanup_images(older_than_days=30, dry_run=False)
cleanup_summaries(older_than_days=90, dry_run=False)

# Local storage tools (sessions, images, registries)
pytest test_server.py -v

# Project sync tools (context_bridge package)
pytest tests/ -v

# All tests
pytest test_server.py tests/ -v