AI编码助手记忆服务器

┌─────────────────────────────────────────────────────────────────┐
│               Claude Code / Cursor / Windsurf                   │
│                       (MCP Client)                              │
└──────┬──────────────────┬──────────────────────┬────────────────┘
       │                  │                      │
  [Stdout/Stdin]   [Hook: Stop/PreCompact]  [Hook: UserPromptSubmit
  (MCP Tools)       (save observations)      /SessionStart]
       │                  │                  (recall context)
       v                  v                      │
┌────────────┐  ┌──────────────────┐             v
│ MCP Server │  │ Hook Subprocess  │   ┌──────────────────┐
│(stdio mode)│  │   --hook mode    │   │ Recall Subprocess│
└─────┬──────┘  └────────┬─────────┘   │  --recall mode   │
      │                  │             └────────┬─────────┘
      │  5 Tools         │ Transcript           │ FTS5 search
      │  observe/recall/ │ parsing &            │ keyword extraction
      │  reflect/        │ observation          │ (no LLM, ~50ms)
      │  get_session_info│ extraction           │
      │  switch_context  │                      │
      v                  v                      v
┌──────────────────────────────────────────────────────┐
│                  Agents Layer                         │
│  ┌──────────┐  ┌──────────┐  ┌──────────────┐       │
│  │ Observer  │  │Reflector │  │ Categorizer  │       │
│  │ extract   │  │ compress │  │ classify     │       │
│  └────┬─────┘  └────┬─────┘  └──────┬───────┘       │
└───────┼──────────────┼───────────────┼───────────────┘
        │              │               │
        v              v               v
┌──────────────┐  ┌────────────────────────────┐
│ LLM Provider │  │     SQLite Database        │
│ Groq (free)  │  │  sessions / observations   │
│ Google       │  │  reflections / tasks       │
│ OpenAI       │  │  FTS5 full-text search     │
└──────────────┘  └────────────────────────────┘

Capture → Categorize → Store → Search → Compress

Hook fires on Stop/PreCompact
  → Read last 20 transcript messages (JSONL)
  → Skip if < 50 tokens (trivial turn)
  → Skip if already processed (hash dedup)
  → Send to Observer LLM agent
  → Extract observations with priority + category
  → Store each in SQLite (FTS5 auto-indexed)
  → Update session stats
  → Check auto-reflect threshold (default 40K tokens)
     → If over: run Reflector with escalating compression

User types a prompt
  → UserPromptSubmit hook fires
  → Extract keywords from prompt (stop-word filtering, file paths, quoted phrases)
  → FTS5 search with OR query for broad recall
  → Fallback: individual keyword search → category heuristic
  → Inject matching observations as context (max ~1K tokens)
  → Claude sees relevant memories before processing the prompt

AI calls recall(query="authentication")
  → FTS5 full-text search on observations
  → Filter by category / priority / files / branch
  → Group by date with priority emojis
  → Include compressed reflections if requested
  → Include current task context
  → Return formatted observation log

# 1. Add the MCP server
claude mcp add codewatch -- npx codewatch-memory

# 2. Set up automatic hooks (saves + recalls memory without manual tool calls)
npx codewatch-memory --setup

# 3. Set at least one LLM API key for the Observer agent
export GROQ_API_KEY=your-key   # recommended (free tier)

claude mcp add codewatch -- pnpx codewatch-memory
npx codewatch-memory --setup

{
  "servers": {
    "codewatch-memory": {
      "command": "pnpx",
      "args": ["codewatch-memory"],
      "env": {
        "GROQ_API_KEY": "${input:groqApiKey}",
        "CODEWATCH_LLM_PROVIDER": "groq"
      }
    }
  }
}

{
  "mcpServers": {
    "codewatch-memory": {
      "command": "pnpx",
      "args": ["codewatch-memory"],
      "env": {
        "GROQ_API_KEY": "your-key",
        "CODEWATCH_LLM_PROVIDER": "groq"
      }
    }
  }
}

git clone https://github.com/KlausAndrade/codewatch.git
cd codewatch
npm install
npm run build
claude mcp add codewatch -- node /path/to/dist/index.js
npx codewatch-memory --setup

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npx codewatch-memory --hook",
            "timeout": 30,
            "async": true
          }
        ]
      }
    ],
    "PreCompact": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npx codewatch-memory --hook",
            "timeout": 60,
            "async": true
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npx codewatch-memory --recall"
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "matcher": "startup|resume|compact",
        "hooks": [
          {
            "type": "command",
            "command": "npx codewatch-memory --recall"
          }
        ]
      }
    ]
  }
}

# Groq (recommended — fast, free tier available)
export GROQ_API_KEY=your-key

# Google Gemini (cheapest paid option)
export GOOGLE_GENERATIVE_AI_API_KEY=your-key

# OpenAI
export OPENAI_API_KEY=your-key

content: "Chose repository pattern over active record for User module because team needs to swap DB later"
category?: "architecture"  # auto-detected if omitted
priority?: "high"          # auto-assigned if omitted
files?: ["src/repositories/UserRepository.ts"]
source_summary?: "user asked to refactor data access"

query?: "authentication"       # FTS5 full-text search
categories?: ["bugfix", "architecture"]
files?: ["src/auth/middleware.ts"]
priority_min?: "medium"        # high, medium, or low
limit?: 50
include_reflections?: true
branch?: "feature/auth"        # defaults to current branch

compression_level?: 0  # 0=reorganize, 1=light, 2=aggressive, 3=critical
branch?: "main"

branch: "feature/new-ui"  # or "auto" to re-detect from git
carry_task?: true          # carry current task description to new branch

npm install
npm run build        # Compile TypeScript
npm run dev          # Watch mode
npm test             # Run tests
npm run test:watch   # Watch mode tests

src/
├── index.ts              # Entry point (MCP server, hook, or recall mode)
├── server.ts             # MCP tool registration
├── config.ts             # Environment config loading
├── hook.ts               # Claude Code hook integration (save observations)
├── recall-hook.ts        # Claude Code hook integration (auto-recall)
├── transcript.ts         # JSONL transcript parser
├── agents/
│   ├── observer.ts       # Observer agent (extract observations)
│   ├── reflector.ts      # Reflector agent (compress observations)
│   ├── categorizer.ts    # Heuristic + LLM categorization
│   └── prompts.ts        # All agent prompt templates
├── storage/
│   ├── database.ts       # SQLite schema + initialization
│   ├── observations.ts   # Observation CRUD + FTS5 queries
│   ├── reflections.ts    # Reflection storage
│   ├── sessions.ts       # Session management
│   └── queries.ts        # Current task queries
├── tools/
│   ├── observe.ts        # MCP tool handler
│   ├── recall.ts         # MCP tool handler
│   ├── reflect.ts        # MCP tool handler
│   ├── get-session-info.ts
│   └── switch-context.ts
├── llm/
│   └── provider.ts       # Multi-provider LLM with fallback
├── git/
│   └── branch.ts         # Branch detection with 10s cache
└── utils/
    ├── tokens.ts         # Token estimation (chars/4)
    ├── stdin.ts          # Shared stdin reader for hooks
    ├── sanitize.ts       # XML parsing, line truncation
    └── repetition.ts     # Degenerate output detection