team-memory

Team Memory

Persistent memory and evolving personality for AI teammates.

Related: For session journaling use the chronicle skill. For persona/profile mechanics use the persona-memory skill.

File paths like scripts/init.sh and references/design.md are relative to this skill's base directory; run the commands below from there. Memory lives under ~/.ai-memory/ (override with AI_MEMORY_DIR). Prerequisite: Claude Code.

Usage

/team-memory init <name>       # Bootstrap a new teammate
/team-memory list              # Show all teammates
/team-memory switch <name>     # Set active teammate
/team-memory status            # Memory stats for active teammate
/team-memory status <name>     # Memory stats for specific teammate
/team-memory consolidate       # Run consolidation on demand
/team-memory forget <query>    # Find and remove matching memories

Verification

Run regression smoke checks:

bash tests/regression.sh

Transcript fallback behavior:

• Default: SessionEnd requires hook-provided transcript_path (safer under concurrency)
• Optional fallback: set AI_MEMORY_ALLOW_TRANSCRIPT_FALLBACK=1

Init (/team-memory init <name>)

Bootstrap a new AI teammate:

bash scripts/init.sh <name>

This creates:

• ~/.ai-memory/<name>/ with CLAUDE.md, personality.md, relationship.md
• ~/.ai-memory/<name>/core/ — always-loaded memory blocks
• ~/.ai-memory/<name>/archival/ — searchable deep storage
• ~/.ai-memory/<name>/journal/ — session summaries
• ~/.ai-memory/shared/ — cross-teammate knowledge (if first teammate)
• SessionEnd hook for sleep-time compute

After init, edit:

1. ~/.ai-memory/<name>/personality.md — define the teammate's identity
2. ~/.ai-memory/shared/projects.md — add project context (first teammate only)

For the full walkthrough, see references/add-teammate.md.

Launch

Launch Claude with a teammate personality:

scripts/launch.sh                    # active teammate
scripts/launch.sh --persona <name>   # specific teammate
scripts/launch.sh --persona <name> ~/code/project

Recommended alias — <team-memory base dir> here and below is this skill's base directory, announced at invocation; substitute the real path when writing into a shell rc (an alias must hold a resolved path):

alias claude-memory="<team-memory base dir>/scripts/launch.sh"
alias claude-bertram="<team-memory base dir>/scripts/launch.sh --persona bertram"

List (/team-memory list)

Show all teammates in ~/.ai-memory/:

ls -1 ~/.ai-memory/ | grep -v shared | grep -v active

Show which is active:

readlink ~/.ai-memory/active

Switch (/team-memory switch <name>)

Update the active teammate symlink:

ln -sfn <name> ~/.ai-memory/active

Status (/team-memory status [name])

Show memory statistics for a teammate:

• Count of core/ blocks
• Count of archival/ blocks
• Count of journal/ entries
• Confidence distribution across blocks
• Last consolidation date
• Personality version

PERSONA="${1:-$(readlink ~/.ai-memory/active)}"
echo "Teammate: $PERSONA"
echo "Core blocks: $(ls ~/.ai-memory/$PERSONA/core/*.md 2>/dev/null | wc -l)"
echo "Archival blocks: $(ls ~/.ai-memory/$PERSONA/archival/*.md 2>/dev/null | wc -l)"
echo "Session journals: $(ls ~/.ai-memory/$PERSONA/journal/*.md 2>/dev/null | wc -l)"

Consolidate (/team-memory consolidate)

Run the consolidation pipeline on demand (normally runs at session end):

Dispatch the sleep-consolidate agent:

Task tool:
  subagent_type: "general-purpose"
  prompt: "Read <team-memory base dir>/references/agents/sleep-consolidate.md and execute. Persona: <name>, Memory dir: <MEMORY_DIR>/<name>"

Forget (/team-memory forget <query>)

Search for and remove matching memories:

1. Search archival/ and core/ for blocks matching the query
2. Show matches to the user for confirmation
3. Delete confirmed blocks

Never delete without user confirmation.

Architecture

Memory Hierarchy

Two Memory Loops

Two loops. During a session, the teammate's CLAUDE.md instructs it to dispatch background remember and recall agents when encountering decisions, patterns, or needing prior context. After the session, a SessionEnd hook fires the sleep pipeline — extract, consolidate, reflect.

1. Extract — find memories the active loop missed in the transcript
2. Consolidate — merge duplicates, apply confidence decay, promote/demote
3. Reflect — evolve relationship.md and mutable personality sections

Memory Block Format

---
type: decision|pattern|insight|preference|fact
confidence: 0.0-1.0
source: user|session|consolidation|promotion
created: YYYY-MM-DD
updated: YYYY-MM-DD
tags: [topic, project]
project: optional
---

Concise memory content with enough context to be useful
without the original conversation.

Staleness

Blocks not updated in 30+ days lose 0.1 confidence (facts exempt). Blocks below 0.3 confidence are pruned during consolidation. Blocks that stay relevant get refreshed by merges and re-references.

Sample Personalities

A sample Bertram personality is available at references/sample-bertram-personality.md.

Copy and customize for your teammate.