Skip to main content
Glama
crewmemory
by GIGAParviz

Install

uvx --from crewmemory-mcp crewmemory install codex --repo https://github.com/org/crewmemory.git --user alice --launcher uvx

Replace 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 alice

On 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 identity

Verify anytime

crewmemory doctor          # config, connectivity, project detection, counts

Related 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-browser

A 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 ui

Member 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

team_context (start-here briefing), MCP prompts session_start / session_end / pr_review_flow

Smart retrieval

recall — ranked by relevance × recency × confidence, packed into a context budget; searches team + personal scopes

Raw search

search_memory (filters: kind/tags/author/file/project), list_recent, memory_stats (auto index), recent_activity

Save knowledge

save_note, log_decision (context+decision+rationale), log_solution (problem/error/fix), save_gotcha, save_pattern, remember_commit_digest (summarize commits)

Presence

update_status(task, progress%, blockers), get_team_status, profiles via set_my_profile/get_profile

Handoffs

save_handoff (summary/next steps/blockers/questions), latest_handoff

Lifecycle

verify_memory, flag_stale, mark_superseded(old, new), find_duplicates (dedupe/consolidation)

Git-native

entry_history (commit-level provenance), memory_at(ref) (time travel to tag/sha/branch), sync_memory (manual pull/push; offline writes queue locally)

Code-aware

why_code(path) ("why does this exist?"), pr_memory_review(base) (decisions invalidated by a PR), git_blame_context(file, lines)

For humans

crewmemory ui dashboard — statuses, blockers, activity, memory browser, profiles

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 --follow history per memory

  • Time travel: read crew memory at any commit/tag/branch

  • Branch-aware context: entries remember project+branch; recall boosts current-branch matches

  • Context budget management: recall packs the best memories into a char budget

  • Code 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 profiles

Configuration (per teammate)

Variable

Required

Meaning

CREWMEMORY_REPO_URL

yes

memory repo URL

CREWMEMORY_USER

yes

identity (author, commits, status)

CREWMEMORY_TOKEN

private repos

PAT with Contents Read+Write

CREWMEMORY_EMAIL

no

commit email

CREWMEMORY_BRANCH

no

pin a branch

CREWMEMORY_PROJECT_PATH

no

code repo path (auto-detected from cwd otherwise)

CREWMEMORY_HOME

no

data dir (default ~/.crewmemory)

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.

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 doctor diagnoses 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_memory later.

  • "Points to a different remote" → delete ~/.crewmemory/<repo> or set CREWMEMORY_LOCAL_PATH.

Available Tools

30 tools
delete_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

    A3.5/5.0

    Scored across 30 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count2/5

    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.

    Completeness5/5

    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

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Shared, 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.
      11
      41
      GPL 3.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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.
      6
      Apache 2.0