teammind 0.2.0 → 0.2.2

package/README.md

@@ -9,40 +9,48 @@
     ╚═╝   ╚══════╝╚═╝  ╚═╝╚═╝     ╚═╝╚═╝     ╚═╝╚═╝╚═╝  ╚═══╝╚═════╝
 ```
 
-**Git-aware persistent memory for Claude Code teams**
+**Git-aware persistent memory for Claude Code teams — and a personal AI that learns how you work**
 
 [![npm version](https://img.shields.io/npm/v/teammind?color=blue&style=flat-square)](https://npmjs.com/package/teammind)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-green?style=flat-square)](https://nodejs.org)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](LICENSE)
-[![Claude Code](https://img.shields.io/badge/Claude%20Code-compatible-purple?style=flat-square)](https://claude.ai/code)
+[![Claude Code](https://img.shields.io/badge/Claude%20Code-hooks-purple?style=flat-square)](https://claude.ai/code)
 [![No API key](https://img.shields.io/badge/API%20key-not%20required-brightgreen?style=flat-square)](#)
 
-*Every insight your team discovers with Claude Code — remembered forever.*
+*Every insight your team discovers — remembered forever. Every preference you have — written to CLAUDE.md automatically.*
 
 </div>
 
 ---
 
+## Two things TeamMind does
+
+**1. Team memory** — captures what your team learns with Claude Code and shares it across every developer's sessions automatically.
+
+**2. Personal persona** — watches how you interact with Claude Code, figures out your preferences, and writes them directly to `~/.claude/CLAUDE.md`. Claude reads that file in every project, so it adapts to how you work without you ever having to explain yourself again.
+
+---
+
 ## The problem
 
 Claude Code is stateless. Every session starts fresh.
 
-Alice spends 3 hours debugging a race condition, discovers the root cause, fixes it. Bob hits the exact same bug the next morning — his Claude has no idea what Alice learned. The senior dev who knows why the auth middleware skips OPTIONS requests goes on vacation. The codebase has 40 undocumented gotchas that only exist in old conversations.
+Alice spends 3 hours debugging a race condition, finds the root cause, fixes it. Bob hits the exact same bug the next morning — his Claude has no idea what Alice learned. The senior dev who knows why the auth middleware skips OPTIONS requests goes on vacation. The codebase has 40 undocumented gotchas that only exist in old Slack threads.
 
-**TeamMind fixes this.** It silently captures what your team learns in Claude Code sessions and makes that knowledge available to every developer's Claude — automatically, forever.
+**TeamMind fixes this.** It silently captures what your team learns and makes that knowledge available to every developer's Claude — automatically, from the first prompt.
 
 ---
 
-## Install
-
-**One command. 30 seconds. No API key.**
+## Get started in 30 seconds
 
 ```bash
-npx teammind init
+npm install -g teammind
+teammind init
 ```
 
+That's it. No API key. No config. No server to run.
+
 ```
-✓ Claude Code detected
 ✓ Hooks installed in ~/.claude/settings.json
 ✓ MCP server registered
 ✓ Embedding model ready (38MB, runs locally)
@@ -51,240 +59,226 @@ npx teammind init
 TeamMind is active. Just use Claude Code normally.
 ```
 
-That's it. No API key. No server. No config.
+> **Already have it?** Update with `npm install -g teammind@latest`
 
 ---
 
 ## How it works
 
+Open Claude Code → TeamMind silently injects relevant memories into Claude's context before you type a word. Close Claude Code → TeamMind scans the transcript in the background and saves anything worth remembering.
+
 ```
-YOUR SESSION                         BACKGROUND
-──────────────────                   ──────────────────────────────────
-You open Claude Code
-        │
-        ▼
-SessionStart hook fires
-TeamMind injects team
-context into Claude's
-initial prompt
-  ┌─────────────────────┐
-  │ [gotcha] Auth skips │
-  │ OPTIONS for CORS    │
-  │ [bug] Prisma times  │
-  │ out at 5s on large  │
-  │ checkouts           │
-  └─────────────────────┘
-
-Claude already knows
-before you type a word
-        │
-        ▼
-Mid-session: Claude calls
-memory_search / memory_add
-as it encounters files
-        │                             SESSION ENDS
-        ▼                                    │
-You close Claude Code ──────────────────────►│
-                                             ▼
-                                      Stop hook fires
-                                      Transcript saved to DB
-                                             │
-                                             ▼ (fully detached, no API call)
-                                      Local signal analysis
-                                      scans assistant turns for
-                                      high-value patterns
-                                             │
-                                             ▼
-                                      Memories embedded locally
-                                      Stored with git metadata
-                                      File hashes saved for
-                                      staleness detection
+┌─ SESSION START ──────────────────────────────────────────────┐
+│                                                               │
+│  Claude receives your team's memories automatically:         │
+│                                                               │
+│  <team_memory project="myapp" branch="main">                 │
+│  1. [gotcha] Stripe webhook needs raw Buffer before           │
+│     constructEvent() — src/webhooks/stripe.ts                │
+│  2. [bug] Prisma timeout at 5s on large checkouts            │
+│  3. [decision] Idempotency keys on all payment intents       │
+│  </team_memory>                                              │
+│                                                               │
+└───────────────────────────────────────────────────────────────┘
+         Claude already knows this before you say anything.
+
+┌─ SESSION END (background, ~1 second) ────────────────────────┐
+│                                                               │
+│  TeamMind scans assistant turns for high-value signals:      │
+│  "the reason we..." / "note that..." / "fixed by..."         │
+│                                                               │
+│  Extracts → embeds locally → deduplicates → stores           │
+│  with git metadata and file hashes for staleness detection   │
+│                                                               │
+└───────────────────────────────────────────────────────────────┘
 ```
 
 ---
 
-## Features
+## Personal persona — writes to your CLAUDE.md
 
-| | |
-|---|---|
-| **No API key required** | Extraction runs entirely on-device using local signal heuristics. Zero cost, zero setup. |
-| **Silent operation** | Injects memory context before your first prompt. Captures learnings after your last. You never see it working. |
-| **Git-aware** | Memories are tagged with branch and commit. Files referenced by a memory are hashed — when those files change, the memory is marked stale automatically. |
-| **Zero native deps** | Uses Node.js built-in `node:sqlite`. No compilation, no Visual Studio, no Python. Works on Mac, Linux, and Windows out of the box. |
-| **Local-first** | Embeddings and extraction run fully in-process. Your code never leaves your machine. |
-| **Team sync** | Export memories to a JSON file, commit it to your repo, teammates import on `git pull`. |
-| **MCP tools** | Claude can search, add, and check memory freshness mid-session via 4 MCP tools. |
+TeamMind watches your sessions for signals about how you prefer to work with Claude — things like "be more concise", "just do it", "show me the code first", "stop summarizing". It aggregates these across sessions and writes them directly to `~/.claude/CLAUDE.md`.
 
----
+Since `~/.claude/CLAUDE.md` is the global instructions file that Claude Code reads at the start of **every** session in **every** project, your preferences travel with you automatically — no setup per project, no repeating yourself.
 
-## CLI Reference
+```
+~/.claude/CLAUDE.md
+
+<!-- teammind-persona:start -->
+
+## User Interaction Preferences
+
+- Keep responses concise — avoid lengthy explanations
+- Take action directly — do not ask for confirmation on straightforward tasks
+- Show code directly rather than describing it first
+
+<!-- teammind-persona:end -->
+```
+
+TeamMind only touches the section between its markers — everything else in your CLAUDE.md stays exactly as it is.
 
 ```bash
-# Setup
-npx teammind init              # one-time setup — patches Claude Code settings
-
-# Daily use
-teammind status                # memory stats for the current project
-teammind memories              # browse all memories
-teammind memories "auth"       # search memories by keyword
-teammind sessions              # see captured sessions (processed / pending)
-teammind forget <id>           # delete a specific memory
-teammind forget --stale        # bulk-delete all stale memories
-
-# Extraction
-teammind extract --pending     # manually trigger extraction for pending sessions
-
-# Team sync
-teammind team                  # interactive team setup wizard
-teammind team --export ./path  # export memories to JSON
-teammind team --import ./path  # import memories from JSON
+teammind persona              # see your current preferences
+teammind persona --update     # re-analyze sessions and rewrite to CLAUDE.md
+teammind persona --reset      # remove the section from CLAUDE.md
 ```
 
+**What it detects:** response length, explanation style, code-first vs description-first, confirmation prompts, formatting preferences, summary behavior.
+
+**What it never touches:** how Claude writes code, architectural choices, language/framework preferences — those belong in your project's CLAUDE.md, not here.
+
 ---
 
-## What gets remembered
+## Daily commands
 
-TeamMind scans each session's assistant turns for high-signal patterns — no API call needed:
+```bash
+# See what TeamMind knows about your current project
+teammind status
 
-| Captured | Not captured |
-|---|---|
-| Bugs found and their root cause | Generic programming advice |
-| Architectural decisions and *why* | Things obvious from reading the code |
-| Non-obvious gotchas | Temporary debugging steps |
-| API quirks and workarounds | Standard library usage |
-| Performance findings | Basic code explanations |
-| Security considerations | |
-| Important config constraints | |
+# Browse all memories
+teammind memories
+
+# Search memories
+teammind memories "stripe webhook"
+
+# Filter by type
+teammind memories --tag bug
+teammind memories --tag decision
+teammind memories --tag gotcha
 
-The extractor looks for causal reasoning ("instead of X because Y"), gotcha markers ("note that", "watch out", "caveat"), bug/fix patterns, and decision language — the same things a senior dev would highlight in a code review comment.
+# Read a memory in full
+teammind memory <id>
 
-Each memory is stored with:
-- The files it relates to (for staleness detection)
-- The git commit and branch it was discovered on
-- Who discovered it
-- A semantic embedding (for smart retrieval)
+# Delete a memory
+teammind forget <id>
+teammind forget --stale        # clear outdated memories
+teammind forget --all          # wipe everything for this project
+```
+
+```bash
+# Build / update your personal preferences in CLAUDE.md
+teammind persona
+teammind persona --update
+```
+
+**`teammind status` shows a live breakdown:**
+```
+TeamMind — myapp
+────────────────────────────────────────
+  31 fresh memories  •  2 stale  •  last captured today
+
+  By type:
+    bug          ██████████ 12
+    decision     ███████ 8
+    gotcha       █████ 6
+    security     ████ 5
+    config       ██ 3
+
+  Recent:
+  • [gotcha] Stripe webhook must receive raw Buffer before constructEvent()  — today
+  • [bug] Prisma transaction timeout at 5s on large cart checkouts  — today
+  • [decision] Switched to idempotency keys after double-charge incident  — 2d ago
+```
 
 ---
 
-## Team Sync
+## Sharing with your team
 
-### Option 1: Git (recommended)
+Export your memories to a file and commit it:
 
 ```bash
-# On your machine
+# Export
 teammind team --export .claude/team-memories.json
-git add .claude/team-memories.json
-git commit -m "chore: add team memories"
-git push
+git add .claude/team-memories.json && git commit -m "chore: team memories" && git push
 
-# On your teammate's machine
-git pull
+# Import (your teammates run this after pulling)
 teammind team --import .claude/team-memories.json
 ```
 
-Auto-import on every `git pull` with a post-merge hook:
+Auto-import every time someone pulls:
 ```bash
 echo 'teammind team --import .claude/team-memories.json' >> .git/hooks/post-merge
 chmod +x .git/hooks/post-merge
 ```
 
-### Option 2: Self-hosted sync *(coming soon)*
-
-Run a sync server on your own infra. All team members point to it.
+---
 
-### Option 3: TeamMind Cloud *(coming soon)*
+## What gets captured
 
-Hosted sync, free for teams under 5.
+TeamMind scans assistant turns for signal language — no API call, no cost:
 
----
+| Captured | Skipped |
+|---|---|
+| Root causes of bugs | Generic programming advice |
+| Architectural decisions and *why* | Obvious things from reading the code |
+| Non-obvious gotchas | Temporary debugging that was reverted |
+| API quirks and workarounds | Standard library usage |
+| Security considerations | Basic code explanations |
+| Performance findings | |
+| Config constraints | |
 
-## Configuration
+It looks for causal reasoning (`"instead of X because Y"`), gotcha markers (`"note that"`, `"watch out"`), bug/fix patterns, and decision language — the same things you'd write in a code review comment.
 
-```bash
-# View all config
-teammind config list
+Memory types: `bug` · `decision` · `gotcha` · `security` · `performance` · `config` · `api` · `pattern`
 
-# Adjust injection (default: 10 memories per session start)
-teammind config set max_inject 15
+---
 
-# Disable auto-extraction (manual memory_add only)
-teammind config set extraction_enabled false
+## MCP tools (mid-session)
 
-# Adjust dedup sensitivity (default: 0.88)
-teammind config set similarity_threshold 0.85
-```
+Claude can call these tools during a session without you asking:
 
-Config is stored at `~/.teammind/config.json`.
+| Tool | What it does |
+|---|---|
+| `memory_search` | Semantic search across team memories |
+| `memory_add` | Save a new insight manually |
+| `memory_list` | List recent memories for this project |
+| `memory_stale` | Check which memories may be outdated |
 
 ---
 
-## Memory lifecycle
+## Staleness detection
+
+When a memory references a file, TeamMind stores a hash of that file. On every session start it re-hashes and compares. If a file changed, the memory gets flagged:
 
 ```
-Session ends
-    │
-    ▼
-Transcript saved to ~/.teammind/db.sqlite
-    │
-    ▼ (background process, ~1 second, no network)
-Local heuristic extraction
-Scans assistant turns for high-signal paragraphs
-Extracts 0–10 high-value memories
-    │
-    ▼
-Each memory is:
-  • Embedded locally (all-MiniLM-L6-v2, 384 dims)
-  • Tagged with file paths + function names
-  • Hashed against current file contents
-  • Stored with git metadata
-    │
-    ▼
-Next session start:
-  Top 10 memories injected into Claude's context
-  File hashes checked → stale memories flagged
-  Claude calls memory_search as needed
+• [gotcha] ⚠ STALE  Auth middleware skips OPTIONS for CORS
 ```
 
----
+It still injects but warns Claude not to rely on it. `teammind forget --stale` clears them all.
 
-## What Claude sees
+---
 
-At the start of every session on a project with memories:
+## Configuration
 
-```xml
-<team_memory project="myapp" branch="feature/payments">
-1. [gotcha] Stripe webhook must receive raw Buffer body before constructEvent() — src/webhooks/stripe.ts
-2. [decision] Using idempotency keys on all payment intents — decided after double-charge incident Jan 2026
-3. [bug] Prisma transaction timeout at 5s hits on large cart checkouts — src/db/checkout.ts
-4. [pattern] All currency stored as integers (cents), never floats
-5. [config] TEST_MODE=true bypasses Stripe in dev, but still hits real webhooks endpoint
-</team_memory>
-(5 of 31 memories — use memory_search tool for more)
+```bash
+teammind config list                          # show current config
+teammind config set max_inject 15             # inject more memories per session (default: 10)
+teammind config set extraction_enabled false  # disable auto-extraction
+teammind config set similarity_threshold 0.85 # dedup sensitivity (default: 0.88)
 ```
 
-Claude reads this before you type a word. It uses `memory_search` mid-session to pull deeper context when it needs it.
-
 ---
 
-## Privacy
+## Sessions
 
-- **Your code never leaves your machine** — extraction is fully local, no API calls
-- **Embeddings run locally** using `@huggingface/transformers` — no API calls for search
-- **No telemetry** — TeamMind makes zero network requests on its own
-- **Team export** scans for secrets before writing (API keys, tokens, passwords are redacted)
-- **Self-hostable** — run everything on your own infra if needed
+```bash
+teammind sessions              # see all captured sessions
+teammind extract --pending     # manually process any unextracted sessions
+```
+
+If TeamMind is running but you're not seeing memories yet, run `teammind extract --pending` — it processes any sessions that haven't been extracted yet.
 
 ---
 
 ## How it hooks into Claude Code
 
-TeamMind adds two hooks and one MCP server to `~/.claude/settings.json`:
+TeamMind patches `~/.claude/settings.json` during `init`:
 
 ```json
 {
   "hooks": {
-    "SessionStart": [{ "hooks": [{ "type": "command", "command": "node ... inject" }] }],
-    "Stop":         [{ "hooks": [{ "type": "command", "command": "node ... capture" }] }]
+    "SessionStart": [{ "hooks": [{ "type": "command", "command": "node ~/.teammind/hooks/session-start.js" }] }],
+    "Stop":         [{ "hooks": [{ "type": "command", "command": "node ~/.teammind/hooks/session-stop.js"  }] }]
   },
   "mcpServers": {
     "teammind": { "type": "stdio", "command": "node", "args": ["...", "server"] }
@@ -292,55 +286,18 @@ TeamMind adds two hooks and one MCP server to `~/.claude/settings.json`:
 }
 ```
 
-**SessionStart** runs before your first prompt and prints team memories to stdout — Claude Code injects this as context.
-
-**Stop** fires when Claude finishes. It saves the transcript and spawns a detached background process for extraction. You feel zero latency.
-
-**MCP server** gives Claude 4 tools: `memory_search`, `memory_add`, `memory_list`, `memory_stale`.
+- **SessionStart** — prints memories to stdout, Claude Code injects them as context
+- **Stop** — saves the transcript, spawns a detached background worker (you feel zero latency)
+- **MCP server** — gives Claude the 4 tools above during sessions
 
 ---
 
-## MCP Tools
-
-Claude has these tools available mid-session:
-
-#### `memory_search`
-```
-Search team memory for relevant context about code, bugs, decisions, or patterns.
-Parameters: query (string), file_path? (string), limit? (number)
-```
-
-#### `memory_add`
-```
-Save an important insight, decision, bug fix, or pattern to team memory.
-Parameters: content (string), summary (string), tags? (string[]), file_paths? (string[]), functions? (string[])
-```
-
-#### `memory_list`
-```
-List recent memories for the current project.
-Parameters: limit? (number)
-```
-
-#### `memory_stale`
-```
-Check which memories may be outdated because their referenced files changed.
-Parameters: (none)
-```
-
----
-
-## Staleness detection
-
-When TeamMind saves a memory that references a file, it stores a SHA-256 hash of that file at that moment.
-
-Every session start, it re-hashes all referenced files and compares. If a file changed:
-- The memory is marked `stale`
-- It still injects with a `[may be outdated]` tag
-- It's deprioritized in ranking
-- `teammind forget --stale` clears them in bulk
+## Privacy
 
-This means memories about refactored code don't silently mislead future sessions.
+- **No code leaves your machine** — extraction is entirely local, zero network requests
+- **Embeddings run locally** via `@huggingface/transformers`
+- **No telemetry** of any kind
+- **Secrets are redacted** before team export (API keys, tokens, passwords)
 
 ---
 
@@ -348,22 +305,20 @@ This means memories about refactored code don't silently mislead future sessions
 
 - Node.js ≥ 18.0.0
 - Claude Code (any version with hooks support)
-- Git (for git-aware features)
+- Git (optional — for branch/commit metadata)
 
-No API key. No cloud account. No native compilation.
+No API key. No cloud account. No native compilation. Works on Mac, Linux, and Windows.
 
 ---
 
 ## License
 
-MIT — use it, fork it, build on it.
+MIT
 
 ---
 
 <div align="center">
 
-Built for teams who use Claude Code seriously.
-
 [npm](https://npmjs.com/package/teammind) · [Issues](https://github.com/natedemoss/Teammind/issues)
 
 </div>