Git-Native Memory System (Hindsight-Inspired)

Status: historical plan (March 2026). Recall and voting have since shipped; current behavior is in the Usage Guide.

Generated by /plan-ceo-review on 2026-03-28 Branch: master | Mode: SELECTIVE EXPANSION Repo: teamai/teamai-cli Reference: vectorize-io/hindsight — Agent Memory Framework

Overview

Borrow Hindsight's three-layer retain/recall/reflect memory model and implement automatic recall of team knowledge with Git plus a local search index. This adds the read path that session contribute (the write path) was missing, so the AI remembers other people's experience while it works.

Vision

Upgrade teamai from a file-sync tool to a team memory system. The knowledge flywheel:

write → index → search → vote → rank → better search

Architecture

                    ┌─────────────────────────────────┐
                    │      TEAM GIT REPO               │
                    │  learnings/                       │
                    │    ├── k8s-oom-triage-2026-03-15.md │
                    │    └── api-timeout-fix-2026-03-20.md │
                    │  votes/                           │
                    │    ├── jeff.yaml                  │
                    │    └── alice.yaml                 │
                    └──────────┬────────────────────────┘
                               │
                    ┌──────────┴──────────┐
                    │                     │
              teamai pull           teamai contribute
              + index rebuild       (existing, enhanced)
                    │                     │
                    ▼                     │
    ┌───────────────────────────┐         │
    │  ~/.teamai/               │         │
    │    learnings/ (local copy)│◀────────┘
    │    search-index.json      │
    │    user-votes/<user>.yaml │
    └──────────┬───────────────┘
               │
         teamai recall "api timeout"
               │
               ▼
         Ranked results → recalled_count++
                              │
              (adoption evidence: agent opens the doc, or
               opt-in LLM-judge) → upvoted_count++

Hindsight Mapping

Hindsight Concept	TeamAI Implementation	Status
Retain (store)	teamai contribute → learnings/ in git + frontmatter	✅ Done (enhanced)
Recall (retrieve)	teamai recall <query> → local search index (BM25 + Intl.Segmenter)	🔨 This plan
Reflect (learn)	teamai reflect → LLM analyzes learnings → meta-insights	⏳ Deferred
Memory Bank isolation	Per-user directories in git repo	✅ Existing
Ranking/relevance	Recall bumps recalled_count; adoption evidence (agent opened the doc, or the opt-in LLM-judge) bumps upvoted_count → votes/.yaml → aggregate at pull (#723)	🔨 This plan

Key Design Decisions

#	Decision	Choice	Rationale
1	Storage backend	Git repo (no PostgreSQL/vector DB)	Zero external dependencies, matches teamai philosophy
2	Search method	Keyword matching + Intl.Segmenter	Handles CJK text, no embedding cost, sufficient for V1
3	Index location	Local-only search-index.json	Rebuilt at pull time, no sync conflicts
4	Vote mechanism	Per-user YAML; recall bumps recalled_count, adoption evidence (tool-use / opt-in LLM-judge) bumps upvoted_count (#723)	Idempotent, zero Git conflict, knowledge self-curates
5	Frontmatter	Required in SKILL.md template	Structured metadata improves search precision
6	AI integration	Rule injection → AI calls recall via Bash	Works across all AI tools, no tool-specific integration

Implementation Phases

Phase 1: Foundation (pull sync + index)

1. src/types.ts — LearningDoc, SearchIndex types
2. src/utils/search-index.ts — buildIndex(), loadIndex(), search() with Intl.Segmenter
3. src/pull.ts — syncLearnings() step + index rebuild
4. skill-data/share/SKILL.md — frontmatter standardization (served by teamai skill get share, no longer deployed to each agent)
5. Tests: index build, search, CJK, edge cases

Phase 2: Recall + Voting

1. src/recall.ts — teamai recall CLI command + autoUpvote()
2. src/index.ts — register recall command
3. rules/teamai-recall.md — Rule synced to AI tools
4. Tests: recall CLI, upvote idempotency, vote push

Phase 3: Integration

1. Wire votes into search ranking (pull-time aggregation)
2. Full integration test

Scope Decisions

#	Proposal	Effort	Decision	Reasoning
1	Auto-Recall on SessionStart	M	SUPERSEDED	Replaced by the teamai-recall subagent plus builtin-rules active retrieval
2	Voting: recalled_count + adoption upvote	S	ACCEPTED	Recall increments recalled_count; adoption evidence (tool use, optional LLM judge) increments upvoted_count (#723). Conflict-free, and the key feedback step of the flywheel
3	Frontmatter standardization	S	ACCEPTED	Better search quality, backward compatible
4	Reflect layer	L	DEFERRED	The knowledge base is still cold-starting; not enough data

Deferred to TODOS.md

• Auto-Recall on SessionStart (P2) — replaced by the teamai-recall subagent plus builtin-rules active retrieval (#106)
• Reflect layer (P3) — an LLM analyzes learnings and produces meta-insights; needs 20+ learnings in the knowledge base