teamai-cli/docs/designs/git-native-memory.md

Git-Native Memory System (Hindsight-Inspired)

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

借鉴 Hindsight 的 retain/recall/reflect 三层记忆模型，用 Git + 本地搜索索引实现团队知识的自动回忆。补全 session contribute（写入路径）缺失的"读出路径"，让 AI 在工作时自动"想起"别人的经验。

Vision

把 teamai 从"文件同步工具"升级为"团队记忆系统"。知识飞轮：

写入 → 索引 → 搜索 → 投票 → 排序 → 更好的搜索

Architecture

                    ┌─────────────────────────────────┐
                    │      TEAM GIT REPO               │
                    │  learnings/                       │
                    │    ├── k8s-oom-排查-2026-03-15.md │
                    │    └── api-timeout-修复-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 标准化（由 teamai skill get share 提供，不再部署到各 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	已被 teamai-recall subagent + builtin-rules 主动检索替代
2	投票机制：recalled_count + 采纳 upvote	S	ACCEPTED	Recall 累加 recalled_count；采纳证据（工具使用 / 可选 LLM-judge）累加 upvoted_count（#723）。零冲突，飞轮反馈机制的关键一环
3	Frontmatter 标准化	S	ACCEPTED	提升搜索质量，向后兼容
4	Reflect 层	L	DEFERRED	知识库冷启动阶段，数据不足

Deferred to TODOS.md

• Auto-Recall on SessionStart (P2) — 已被 teamai-recall subagent + builtin-rules 主动检索替代（#106）
• Reflect 层 (P3) — LLM 分析 learnings 生成 meta-insights，需知识库积累到 20+ 篇