Team Memory

Git-native shared development memory for teams using Claude Code.

Team Memory turns durable engineering knowledge into reviewable Markdown in a shared Git repository. Every contributor can pull the same published decisions, procedures, discoveries, failures, and fixes; each machine builds its own disposable SQLite search cache.

Code stays in business Git. Shared knowledge lives in Memory Git. SQLite is local query infrastructure—not a source of truth.

Why Team Memory?

Teams repeatedly rediscover decisions hidden in chat history, reviews, task documents, and old commits. Most agent-memory tools are designed for one person and one local database. Team Memory makes validated knowledge a shared engineering asset:

• Search what another teammate already learned before repeating the investigation.
• Trace every memory back to a Task, session/chunk evidence, repository, branch, commit SHA, and changed paths.
• Review and evolve shared knowledge with ordinary branches, pull requests, CODEOWNERS, git log, and git blame.
• Keep fast local search without creating a shared database, server, daemon, or binary merge conflict.

Highlights

Capability	What it does
Team-shared memory	One shared Memory Git remote. Members query all published team knowledge, not only their own local history.
Git-native auditability	Human-readable Markdown facts and normal Git history provide review, rollback, ownership, and provenance.
Business Git evidence	Memory stores links to real repositories, branches, commits, paths, checkpoints, and task evidence; it never copies business source code.
Local SQLite FTS	.cache/index.db accelerates English, Chinese, and identifier search per machine. Delete it and run team-memory index to rebuild.
Progressive retrieval	search → timeline → show → context narrows evidence before injecting a token-budgeted context block.
Redaction first	API keys, bearer tokens, cookies, passwords, private keys, URL credentials, JWTs, and high-entropy secrets are redacted before persistence.
No hosted backend	No Postgres, Redis, worker, dashboard, vector database, or always-on service is required.

Architecture

flowchart LR
  subgraph Code["Business Git repositories"]
    Repo["Code, branches, commits, pull requests"]
    Artifacts["Task, review, build, and verification artifacts"]
  end

  subgraph Dev["Each contributor's machine"]
    Session["Claude Code sessions"]
    Importer["team-memory import + compile"]
    Cache["Local SQLite FTS cache\n.cache/index.db"]
    Agent["Claude Code"]
  end

  subgraph Shared["Shared Memory Git repository"]
    Tasks["Historical Tasks\nMarkdown + provenance"]
    Memories["Published team memories\nMarkdown + lifecycle"]
    Review["Branches, PRs, and CODEOWNERS"]
  end

  Repo --> Importer
  Artifacts --> Importer
  Session --> Importer
  Importer -->|"redacted candidate facts"| Tasks
  Tasks --> Memories
  Tasks --> Review
  Memories --> Review
  Review -->|"merged knowledge"| Tasks
  Review --> Memories
  Tasks --> Cache
  Memories --> Cache
  Cache -->|"search / timeline / context"| Agent

Loading

Storage model

Layer	Owner	Purpose	Shared?
Business Git	Product/code team	Source code, commits, PRs, task artifacts	Yes, through the existing code workflow
Memory Git	Whole team	Reviewed Tasks and reusable Memories	Yes, through normal Git review
SQLite FTS cache	Individual contributor	Search and context acceleration	No; local and rebuildable

Do not create one shared-memory repository per developer by default. Contributors clone the same logical repository, publish through branches and pull requests, then pull and index everyone else's approved knowledge.

Quick Start

Prerequisites

• Node.js >=22.13
• Git
• A business Git repository to inspect

Install

git clone https://github.com/blain3white/team-memory.git
cd team-memory
npm ci
npm run build
npm link

Local evaluation

team-memory init \
  --repo /absolute/path/to/business-repo \
  --memory /absolute/path/to/memory-repo

export TEAM_MEMORY_CONFIG=/absolute/path/to/memory-repo/config.yaml
team-memory doctor --config "$TEAM_MEMORY_CONFIG"
team-memory sync --config "$TEAM_MEMORY_CONFIG"

init creates an independent Memory Git repository for local evaluation.

Team Setup

Create one shared Memory Git remote. Each contributor clones that remote but keeps an external, machine-local configuration because business repository paths and Claude session roots differ per machine.

git clone <team-memory-remote> /work/team-memory

mkdir -p "$HOME/.config/team-memory"
cat > "$HOME/.config/team-memory/team.yaml" <<'YAML'
version: 1
repository:
  path: /absolute/path/to/business-repo
memory:
  path: /work/team-memory
sessionRoots:
  - /absolute/path/to/.claude/projects
scopes:
  - name: mobile
    paths: [packages/mobile/]
retentionDays: 90
redaction:
  enabled: true
  schemaVersion: 1
YAML

export TEAM_MEMORY_CONFIG="$HOME/.config/team-memory/team.yaml"
git -C /work/team-memory pull --ff-only
team-memory doctor --config "$TEAM_MEMORY_CONFIG"
team-memory index --config "$TEAM_MEMORY_CONFIG"

Add this .gitignore to the shared Memory repository before the first contribution:

.cache/
config.yaml
sessions/
redactions/
runs/
manifest.json

This default policy shares reviewed tasks/ and memories/ while keeping local configuration, raw redacted session archives, and operational audit artifacts out of normal pull requests. Organizations that need to publish complete evidence should use a separate protected evidence repository and explicit retention/access controls.

Team Workflow

1. Capture and compile locally

team-memory import --config "$TEAM_MEMORY_CONFIG"
team-memory compile --config "$TEAM_MEMORY_CONFIG"
team-memory index --config "$TEAM_MEMORY_CONFIG"

import parses eligible Claude JSONL files, redacts content, restores event and tool relationships, chunks the session, and associates business Git evidence conservatively. Ambiguous commit links remain unresolved instead of being guessed. compile turns task observations into lifecycle-managed Memories: create, support, revise, supersede, and deprecate.

2. Publish reviewed knowledge

MEMORY_REPO=/work/team-memory
git -C "$MEMORY_REPO" pull --ff-only
git -C "$MEMORY_REPO" checkout -b memory/<user>/<topic>

team-memory sync --config "$TEAM_MEMORY_CONFIG"

git -C "$MEMORY_REPO" status
git -C "$MEMORY_REPO" add -A
git -C "$MEMORY_REPO" commit -m "docs(memory): capture <topic>"
git -C "$MEMORY_REPO" push -u origin HEAD

Open a pull request and use module owners/CODEOWNERS to review platform-specific knowledge. Do not bypass the shared repository's ignore rules to publish session archives without an explicit policy decision.

3. Use another contributor's memory

git -C /work/team-memory pull --ff-only
team-memory index --config "$TEAM_MEMORY_CONFIG"

team-memory search "refreshTokenOnce" --config "$TEAM_MEMORY_CONFIG" --limit 10
team-memory timeline "refreshTokenOnce" --config "$TEAM_MEMORY_CONFIG"
team-memory show task_abc123 --config "$TEAM_MEMORY_CONFIG"
team-memory context "fix the authentication refresh loop" \
  --config "$TEAM_MEMORY_CONFIG" \
  --budget 1800

context returns historical evidence, not executable instructions. Always verify it against the current business branch and source code before acting.

Why SQLite Is Local

Scenario	Uses SQLite?	Reason
search, timeline, context	Yes	FTS ranks Tasks, Git evidence, and Memories quickly across English, Chinese, and code identifiers.
show <id>, audit, review, recovery	No	Read Markdown facts and Git history directly.
After git pull, first setup, or cache deletion	Rebuild	Run team-memory index; the cache is regenerated from Git-tracked facts.
Cache unavailable	Fallback	Search falls back to reading facts directly.

A shared SQLite database would introduce binary merge conflicts, another authority surface, and more complicated access control. Team Memory intentionally keeps SQLite per machine.

CLI

Command	Purpose
init --repo <path> --memory <path>	Initialize an independent local Memory Git repository.
import	Parse, redact, normalize, scope, and associate eligible Claude sessions with business Git evidence.
compile	Compile Task observations into lifecycle-managed Memory facts.
index	Rebuild the local SQLite FTS cache from fact documents.
sync	Run import → compile → index.
search <query>	Find Tasks, Git evidence, and Memories.
timeline <query-or-id>	Expand related Task/evidence/Memory history.
show <id>	Read a complete Markdown fact and its provenance.
context <query>	Produce a token-budgeted context block for Claude Code.
doctor	Validate configuration, Git repositories, SQLite FTS, redaction, and schema.

All commands output JSON. All write commands support --dry-run.

Claude Code Plugin

The repository includes a Claude Code plugin manifest at .claude-plugin/plugin.json and a /team-memory command at commands/team-memory.md.

Set TEAM_MEMORY_CONFIG in the Claude Code environment. The plugin queries context for relevant work and only runs synchronization when explicitly requested.

Security and Auditability

• Session content is redacted before persistence; redaction reports store finding type, fingerprint, and line—not secret values.
• Tasks and Memories preserve source session, chunk, event IDs, Git evidence, confidence, and lifecycle history.
• Fact paths are constrained to the configured Memory root and written atomically.
• Commit association requires multiple signals; insufficient evidence remains unresolved.
• Git branches, pull requests, CODEOWNERS, git log, and git blame provide the collaboration and audit layer.

Scope and Limitations

• memory.path must currently be the root of its own Git repository. A parent-repository storage mode is planned.
• Team Memory does not implement a hosted identity, authorization, or synchronization service; use your Git platform's access controls and review workflow.
• The default extractor is deterministic. An LLM provider interface exists, but no online provider is bundled.
• There is no PR/Issue connector, Web UI, Postgres, Redis, worker, or vector database.

Related Work

• claude-mem — persistent agent context with local storage and context injection.
• claude-mem-sync — Git-based sharing for claude-mem observations.
• PMB — local-first memory for coding agents with SQLite as its durable store.

Team Memory differs by making Git-tracked Markdown the durable shared fact source and treating SQLite strictly as a per-machine query cache.

Contributing

See CONTRIBUTING.md. Please do not submit real session data, credentials, customer data, or internal source code in issues, tests, examples, or pull requests.

License

Licensed under the Apache License 2.0. Third-party attribution and license texts are available in THIRD_PARTY_NOTICES.md and THIRD_PARTY_APACHE_LICENSE.txt.