crewmemory
CrewMemory is a git-backed shared memory server for AI coding agents, enabling team knowledge capture, retrieval, status tracking, and code-aware memory workflows.
Session briefing: call
team_contextto get project/branch-aware context at session start.Smart retrieval: use
recallfor ranked, budgeted search;search_memory,list_recent,memory_stats, andrecent_activityfor raw or faceted queries.Save team knowledge:
save_note,log_decision,log_solution,save_gotcha,save_pattern,save_handoff, andremember_commit_digest.Lifecycle management:
verify_memory,flag_stale,mark_superseded,find_duplicates,get_memory, anddelete_memory.Git-native sync, provenance, and time travel:
sync_memory,entry_history, andmemory_at.Team presence and profiles:
update_status,get_team_status,latest_handoff,set_my_profile, andget_profile.Code-aware lookups:
why_code,pr_memory_review, andgit_blame_context.Human dashboard: run
crewmemory uilocally to view team status, activity, memories, profiles, and post memories.
Stores and syncs shared team memory in a GitHub repository, automatically committing and pushing saves, pulling latest changes before reads, and supporting history, time travel across refs, and offline-safe sync.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@crewmemory Save this Redis timeout fix as a solution and update my status"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Install
uvx --from crewmemory-mcp crewmemory install codex --repo https://github.com/org/crewmemory.git --user alice --launcher uvxReplace codex with claude-code, claude-desktop, cursor, gemini, opencode, or
windsurf. The same command works on Windows, macOS, and Linux when uv is installed.
Restart the client after registration.
For a private memory repo, also pass --token <fine-grained-token>; use a token limited to that
repository with Contents read/write access.
Install from a source checkout
uv venv .venv
uv pip install --python .venv/bin/python -e .
.venv/bin/crewmemory install codex --repo https://github.com/org/crewmemory.git --user aliceOn Windows, the executable is .venv\Scripts\crewmemory.exe.
Supported clients: claude-code, claude-desktop, codex, cursor, gemini, opencode,
windsurf. The installer backs up and merges existing config, is idempotent, and saves a private
local connection profile so crewmemory doctor and crewmemory ui work outside the agent.
Or just ask your AI
Paste this to the agent running in this folder:
Install yourself as a crewmemory MCP server for Claude Code. My memory repo is https://github.com/org/crewmemory.git, my name is alice, token is github_pat_xxx.
The agent runs crewmemory install claude-code ... for you. No manual tool calls needed.
Project detection
At session start the MCP instructions tell the agent to call
team_context(project_path="<absolute workspace root>"). This selects the current Git repository
and branch dynamically, so one global MCP installation works across projects. crewmemory init
is optional and records a project in the local registry for humans and diagnostics.
crewmemory init # registers the project; reads branch/git identityVerify anytime
crewmemory doctor # config, connectivity, project detection, countsRelated MCP server: contextos-memory
Human dashboard (no agent needed)
crewmemory ui # opens http://127.0.0.1:8765 in your browser
crewmemory ui --port 9000 --no-browserA local web dashboard for the whole team — see everything without asking an agent:
Team now — who is working on what right now, progress bars, ⛔ blockers, stale badges
Activity — full timeline: every note/decision/solution/status/deletion by everyone
Memories — browse & search all six types, filter by author/kind, expand full text
Profiles — member roles, timezones, git identities
Overview — counts by type/author/project/lifecycle + storage info
Post a memory — human-friendly form to publish a shared note, tags, and related files
Binds to 127.0.0.1 only, auto-refreshes every 30s, and accepts posts only from the same local dashboard origin. Zero extra dependencies.
Demo UI
Windows
Fully supported:
uv venv .venv-win
uv pip install --python .\.venv-win\Scripts\python.exe -e .
.\.venv-win\Scripts\crewmemory.exe install claude-code --repo ... --user alice --token ...
.\.venv-win\Scripts\crewmemory.exe uiMember names are sanitized into safe filenames on every platform (_member_filename),
Codex TOML values are properly escaped for Windows paths/backslashes/quotes, and all git
calls run with GIT_TERMINAL_PROMPT=0 so nothing hangs waiting for input.
What your agents can do (tools)
Area | Tools |
Session |
|
Smart retrieval |
|
Raw search |
|
Save knowledge |
|
Presence |
|
Handoffs |
|
Lifecycle |
|
Git-native |
|
Code-aware |
|
For humans |
|
Feature checklist
Shared crew memory on your own git host · personal private memory (local-only scope, never pushed)
Git-native storage: markdown + YAML frontmatter, zero-conflict file strategy (unique filenames, per-user status/activity files)
Auto session sync on every read/write · manual sync tool · offline-safe (writes commit locally, push retries later)
User & member profiles, auto-created from git config (
crewmemory init)Progress tracking & blocker tracking in team status, with staleness markers
Decision memory, gotchas, patterns, solutions, handoffs — six entry types
Memory lifecycle: unverified → verified → superseded/stale, with confidence scores that decay with age and when linked code changes (code-change-aware decay)
Conflict/duplicate detection on save + consolidation finder
Provenance: author attribution, commit-linked memories, full
git log --followhistory per memoryTime travel: read crew memory at any commit/tag/branch
Branch-aware context: entries remember project+branch; recall boosts current-branch matches
Context budget management:
recallpacks the best memories into a char budgetCode integration: file-linked memories power PR-vs-decision review, obsolete-memory detection after PRs, why-does-this-code-exist lookup, blame cross-referencing, commit summarization
Per-project memory: entries are tagged with the detected project slug; status shows project@branch
Faceted search: tags, author, file, type, project (semantic search: future work)
MCP-based, stdio transport, self-hosted/open-source by default
Architecture
Repo layout (created automatically)
notes/ decisions/ solutions/ gotchas/ patterns/ handoffs/ # memory types
status/ current focus per member (task, %, blockers)
activity/ append-only timeline per member
profiles/ member profilesConfiguration (per teammate)
Variable | Required | Meaning |
| yes | memory repo URL |
| yes | identity (author, commits, status) |
| private repos | PAT with Contents Read+Write |
| no | commit email |
| no | pin a branch |
| no | code repo path (auto-detected from cwd otherwise) |
| no | data dir (default |
Manual config snippets (if you prefer editing configs yourself) live in the installer — it writes exactly this shape:
{ "mcpServers": { "crewmemory": {
"command": "/path/to/crewmemory",
"env": { "CREWMEMORY_REPO_URL": "...", "CREWMEMORY_USER": "...", "CREWMEMORY_TOKEN": "..." }
} } }Codex uses [mcp_servers.crewmemory] in ~/.codex/config.toml; OpenCode uses the
mcp.servers.*.type=local shape — both handled by crewmemory install codex/opencode.
Recommended team workflow
Add to your CLAUDE.md / AGENTS.md:
At session start call team_context(project_path="<absolute workspace root>"), then update_status() for your task.
Use recall() before researching anything the team may know.
Save durable learnings immediately (log_solution/log_decision/save_gotcha/save_pattern).
When switching tasks update update_status(); at day's end call save_handoff().Or just use the built-in prompts: /session-start, /session-end, /pr-review-flow.
Write memories that survive the next session
For substantive team knowledge, write a self-contained entry of roughly 150–500 words rather than a one-line recap. Include the applicable parts of this checklist: context and goal; what changed or was learned; evidence (tests, commands, or observed result); rationale and trade-offs; affected files or interfaces; risks or limits; and precise next steps. Use exact paths, commits, error text, and verification results when available. Do not pad routine status updates or invent facts that were not verified.
Security
Never save secrets into memory — it's a readable git repo.
A public memory repository makes every team note, status, path, and handoff public. Prefer private.
Private repos + fine-grained PATs (one per member, Contents: RW) are the intended setup.
Tokens stay in local env/config only; all git output is redacted before reaching agents.
Publishing
The repository includes cross-platform CI, wheel/sdist checks, and a PyPI trusted-publishing workflow. See PUBLISHING.md for the release checklist.
Troubleshooting
crewmemory doctordiagnoses everything and prints exact fixes.Auth failed → token needs Contents Read+Write on the memory repo.
Push failed after retries → change is safe locally (queued); run
sync_memorylater."Points to a different remote" → delete
~/.crewmemory/<repo>or setCREWMEMORY_LOCAL_PATH.
Available Tools
30 toolsdelete_memoryA
Delete your own memory entry. For other people's entries use mark_superseded instead.
Inputs: entry_id (required). Returns: result
entry_historyA
Provenance: every git commit that touched this memory — who changed it, when, and why (commit messages).
Inputs: entry_id (required). Returns: result
find_duplicatesA
Detect duplicate/overlapping memories (similar titles or same linked files) so they can be consolidated.
Inputs: no named parameters. Returns: result
flag_staleA
Flag a memory as stale (probably wrong now, needs re-check). Stale entries are down-ranked heavily.
Inputs: entry_id (required). Returns: result
get_memoryA
Full text of one memory by id (unique prefix ok) including confidence score and lifecycle status.
Inputs: entry_id (required). Returns: result
get_profileA
Read a member profile (default: yours). Includes role, timezone, git identity, about.
Inputs: user. Returns: result
get_team_statusA
See everyone's current task, progress %, blockers and staleness. Read-only.
Inputs: no named parameters. Returns: result
git_blame_contextA
Git blame a line range in YOUR code repo, then cross-reference team memories about that file/authors — answers 'who wrote this and did anyone leave notes about it?'.
Inputs: file_path (required), line_start (required), line_end. Returns: result
latest_handoffA
Get the most recent handoff document (anyone's, or filter by author). Ideal first read when continuing someone's work.
Inputs: author. Returns: result
list_recentA
List newest memories (optionally filter kind or an exact project name; default all projects).
Inputs: kind, limit, project. Returns: result
log_decisionA
Record an architecture/tooling decision: what the situation was, what was decided, why, and which files it affects. Pushed instantly; teammates' agents will consult it.
Inputs: title (required), context (required), decision (required), rationale (required), +2 more. Returns: result
log_solutionB
Record a problem that was hit and its fix (build failures, weird bugs, env issues), optionally with raw error output, so nobody debugs it twice.
Inputs: problem (required), solution (required), tags, files, +1 more. Returns: result
mark_supersededA
Mark an outdated memory as superseded (optionally pointing to the newer replacement id). It stops appearing in recall but stays in history.
Inputs: entry_id (required), replaced_by_id. Returns: result
memory_atA
Time travel: read crew memory AS OF a specific commit SHA, tag or branch of the memory repo. Great for 'what did we know back then'.
Inputs: ref (required), kind, limit. Returns: result
memory_statsA
Automatic index of everything in memory: counts by type, author, lifecycle status, project and top tags.
Inputs: no named parameters. Returns: result
pr_memory_reviewA
Review the CURRENT branch diff against base_ref through the lens of crew memory: finds memories touching changed files, flags decisions/verified knowledge likely made obsolete by this PR, so the AI can supersede/update them.
Inputs: base_ref. Returns: result
recallA
Smart memory retrieval: keyword search ranked by relevance x recency x confidence, packed into a context budget. Searches team (+personal by default, scope='team'|'personal'|'all'). Prefer this over raw search when answering questions.
Inputs: query (required), scope, budget_chars. Returns: result
recent_activityC
Timeline of crew memory activity: statuses, saves, lifecycle changes — newest first, optionally per author.
Inputs: limit, author. Returns: result
remember_commit_digestA
Get a formatted commit log + changed-files summary of base..head from YOUR CODE repo, ready to summarize into a note/decision with save_note/log_decision. The AI writes the actual summary.
Inputs: base_ref (required), head_ref. Returns: result
save_gotchaB
Save a small trap that cost time ('X breaks when Y', 'always Z before W'). Short and punchy.
Inputs: gotcha (required), tags, files, details. Returns: result
save_handoffA
Write a session handoff: what was done, exact next steps, current blockers and open questions. The next session or teammate starts from this instead of zero.
Inputs: summary (required), next_steps (required), blockers, open_questions. Returns: result
save_noteA
Save durable knowledge (conventions, environment quirks, how-to) to shared memory and push instantly. files=[] links related repo paths (enables PR review + decay tracking). scope='personal' keeps it private on this machine. NEVER store secrets.
Inputs: title (required), content (required), tags, files, +1 more. Returns: result
save_patternC
Save a recurring codebase/project pattern others should follow ('how we add an endpoint', error-handling style...).
Inputs: description (required), pattern_name (required), tags, files, +1 more. Returns: result
search_memoryA
Raw faceted search across crew memory. Filters: kind (note|decision|solution|gotcha|pattern|handoff), tags, author, file (path substring), project. Empty query with filters lists matches. Use recall() for smart ranking instead.
Inputs: query (required), file, kind, tags, +3 more. Returns: result
set_my_profileA
Create/update YOUR member profile (role like 'backend dev', timezone, free-text about). Git identity is auto-included when available.
Inputs: role, about, timezone. Returns: result
sync_memoryA
Manual sync with GitHub: direction='pull'|'push'|'both'. Useful after working offline (writes made offline are queued locally and pushed here).
Inputs: direction. Returns: result
team_contextA
Session-start briefing for the current project. Pass the absolute workspace/repo root in project_path so project and branch attribution stay correct across projects. Call this FIRST at every session start.
Inputs: project_path. Returns: result
update_statusA
Announce what you're working on for the whole team: task description, optional progress percent, optional blockers list. Call at session start and whenever the task changes. Teammates see it instantly.
Inputs: task (required), blockers, progress. Returns: result
verify_memoryA
Mark a memory as verified (you checked it is still true). Verified memories rank higher and decay slower.
Inputs: entry_id (required). Returns: result
why_codeA
'Why does this code/file exist?' Lookup across decisions/solutions/gotchas/patterns linked to a path (or mentioning it). Answers come from crew memory, ranked.
Inputs: target (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 30 tools
Each tool targets a distinct action or query type. Even the lookup tools (recall, search_memory, list_recent) have clear differentiators: recall is smart ranking, search_memory is raw faceted filtering, and list_recent is chronological listing. The save tools are clearly separated by memory kind (note, decision, solution, gotcha, pattern, handoff), and lifecycle/status/profile tools have no overlap.
Names follow snake_case with a strong verb-first pattern (save_note, log_decision, get_memory, verify_memory) but there are minor deviations such as 'why_code', 'memory_at', 'team_context', and 'latest_handoff' (non-verb leading). These are still readable and do not disrupt the overall consistency significantly.
30 tools is heavy and above the 25+ threshold. While the breadth covers many memory operations, it feels over-scoped; some tools (e.g., remember_commit_digest, git_blame_context) could be merged into broader workflows. The count likely introduces agent confusion and selection overhead.
The surface fully covers the memory lifecycle: create (save_*, log_decision), retrieve (recall, search_memory, get_memory), update (mark_superseded, verify_memory), delete (delete_memory), discovery (find_duplicates, memory_stats), provenance (entry_history, memory_at), collaboration (status, profiles, handoffs), and integration (sync_memory, pr_memory_review, git_blame_context). No critical gaps are apparent.
Maintenance
Related MCP Connectors
Team memory for AI coding agents and code reviews, reviewed by humans and served over MCP.
Hosted MCP memory for coding agents: persistent across sessions, editable markdown, team sharing.
Shared, scoped, reviewable team memory for AI coding agents.
Memory for AI agent teams across tools, sessions, repositories, and teammates.
Related MCP Servers
- AlicenseAqualityCmaintenanceShared, code-grounded memory for developers and their coding agents. Capture a learning once and the whole team plus every agent recalls it; memory is grounded in your code and stored as git-tracked JSON reviewed in PRs, with citations validated on write and stale memory withheld from recall. Works with any MCP client.1141GPL 3.0
- AlicenseNot gradedqualityCmaintenanceEnables AI coding agents to share a local-first, versioned memory of decisions, conventions, tasks, conflicts, and handoffs over MCP and REST.MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI coding agents to share a persistent local-first memory hub, storing and recalling architectural decisions and context across different tools via MCP, so users can switch assistants without losing context.Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to maintain Git-backed long-term project memory over MCP, supporting on-demand retrieval, curated writes, conflict-safe versioning, idempotency, and crash recovery so new sessions or machines can recover context and continue working.6Apache 2.0