feat: New Feature - Engram Teams

[choiszt]

Summary

Add persistent team memory for Claude Code Agent Teams. When multiple Claude Code agents collaborate as a team, they already share one engram MCP server (same SQLite DB), so real-time memory sharing works for free. This PR adds the missing piece: capturing and consolidating team knowledge after the team ends, so future sessions and teams can build on past work.

What's New

New MCP Tool

• mcp_consolidate_team — Consolidate all memories from an agent team into a structured markdown summary. Accepts optional team_name (auto-detected if omitted). The summary is saved as a searchable memory with tags ['team-summary', 'team:{name}'].

Enhanced MCP Tools

• mcp_save_memory — Auto-tags memories with team:{name} when running in a team context. Transparent, no API change. Also adds contradiction detection: when saving a memory tagged finding, warns if very similar findings already exist (non-blocking).
• mcp_find_similar_sessions — Now surfaces team summaries alongside session indexes, with "Team:" prefix formatting.

New CLI Commands

• engram teams — List past agent teams and their memory counts. Supports --search <query> for semantic search across team summaries.
• engram consolidate — Manually trigger team memory consolidation. Supports --team <name> or auto-detects.

Hook Integration

• Hook configuration for auto-consolidation (e.g., on TaskCompleted or TeammateIdle events) is documented in the project README.md.

Architecture

┌─────────────────────────────────────────────────────────┐
│  packages/core/src/team/                                │
│  ├── detector.ts    — detectTeam(), listTeams()         │
│  ├── consolidate.ts — consolidateTeam() shared logic    │
│  └── index.ts       — re-exports                       │
├─────────────────────────────────────────────────────────┤
│  packages/server/src/server.ts                          │
│  ├── mcp_save_memory      — auto-tag + contradiction    │
│  ├── mcp_consolidate_team — NEW tool                    │
│  └── mcp_find_similar_sessions — includes team-summary  │
├─────────────────────────────────────────────────────────┤
│  packages/cli/src/cli.ts                                │
│  ├── engram teams         — list / search teams         │
│  └── engram consolidate   — trigger consolidation       │
└─────────────────────────────────────────────────────────┘

Core insight: consolidation logic lives in @engram/core and is shared by both the MCP server tool and CLI command — no duplication.

How It Works

1. During team lifetime: All teammates connect to the same engram MCP server → same SQLite DB → real-time memory sharing for free. No extra work needed.
2. Team detection: detectTeam() checks CLAUDE_TEAM_NAME env var, then scans ~/.claude/teams/*/config.json for active teams (returns most recently modified).
3. Auto-tagging: Every mcp_save_memory call during a team session automatically adds team:{name} tag.
4. Consolidation: When a team ends (or on-demand), memories tagged team:{name} are collected, categorized (finding, decision, hypothesis, blocker, action-item, other), and formatted into a structured markdown summary.
5. Discovery: Future sessions find past team knowledge via mcp_find_similar_sessions or engram teams --search.

Files Changed

New Files (7)

File	Lines	Purpose
packages/core/src/team/detector.ts	179	Team detection: detectTeam(), listTeams()
packages/core/src/team/consolidate.ts	166	Consolidation: consolidateTeam()
packages/core/src/team/index.ts	5	Re-exports
packages/core/test/team/detector.test.ts	—	14 unit tests
packages/core/test/team/consolidate.test.ts	—	8 unit tests
packages/server/test/integration/team.integration.test.ts	741	19 integration tests

Modified Files (8)

File	Change
packages/core/src/index.ts	Added team module export
packages/core/tsup.config.ts	Added src/team/index.ts entry
packages/core/package.json	Added ./team subpath export
packages/server/src/server.ts	Auto-tag, consolidate tool, search enhancement, contradiction detection
packages/cli/src/cli.ts	teams + consolidate commands
packages/server/test/server.test.ts	Added detectTeam/consolidateTeam mocks
packages/server/test/e2e/mcp-protocol.e2e.test.ts	Tool count 12→13, added mcp_consolidate_team
README.md	Added Agent Teams hooks documentation

Test Coverage

192 tests pass (41 new), 0 failures, 15 test files

Suite	Tests	Covers
detector.test.ts	14	Env var, fs scan, missing dir, malformed JSON, mtime selection, permission errors
consolidate.test.ts	8	Categorization, empty team, double consolidation, cross-team filtering
team.integration.test.ts	19	Auto-tagging, consolidation round-trip, contradiction detection, CLI commands, edge cases

Design Decisions

Decision	Choice	Rationale
Team tagging	Simple tag team:{name}	No schema migration, uses existing tag system
Consolidation	Shared function in core	Reused by both MCP tool and CLI — no duplication
Team detection	Sync filesystem scan	Small number of local files, acceptable for per-request use
Contradiction threshold	L2 distance < 0.3	Catches near-duplicate findings without false positives
Memory listing	store.list({ limit: 10000 }) + JS filter	No tag index exists; acceptable for local-first use case
Summary persistence	Team summaries persist forever	Organizational knowledge compounds over time

Known Limitations (V1)

• No SQL-level tag filtering: Consolidation fetches all memories (up to 10k) and filters in JS. Acceptable for local use, future optimization candidate.
• detectTeam() per-request: Synchronous filesystem reads on every save. Negligible overhead for typical agent workflows.
• No team lifecycle management: Engram detects teams but doesn't manage them — that's Claude Code's responsibility.

How to Test

pnpm build && pnpm test    # all 192 tests pass

# Manual testing with a team
engram teams                        # list past teams
engram teams --search "auth bug"    # semantic search
engram consolidate --team my-team   # consolidate manually

Related

• Design doc: tasks/team-memory.md
• Branch: feat/swarm
• Claude Code Agent Teams docs: https://code.claude.com/docs/en/agent-teams