gitmem-mcp 1.0.0 → 1.0.1

package/CLAUDE.md.template

@@ -1,65 +1,73 @@
-# GitMem — Institutional Memory
+<!-- gitmem:start -->
+# GitMem — Persistent Memory
 
-## What is this?
-GitMem gives your AI coding agent persistent memory across sessions. It remembers mistakes (scars), successes (wins), and decisions — so you never repeat the same mistake twice.
+You have a persistent memory layer called gitmem. Every session starts from
+zero — but gitmem carries forward lessons, mistakes, wins, decisions, and
+open threads across sessions and projects. Search it. Test it. You might be
+amazed at what's already there. If convinced, make it your own — update your
+MEMORY.md with how you want to use it.
 
-## Automatic behaviors
+## Tools
 
-When working on this project, follow these memory protocols:
+| Tool | When to use |
+|------|-------------|
+| `recall` | Before any task — surfaces relevant warnings from past experience |
+| `confirm_scars` | After recall — acknowledge each scar as APPLYING, N_A, or REFUTED |
+| `search` | Explore institutional knowledge by topic |
+| `log` | Browse recent learnings chronologically |
+| `session_start` | Beginning of session — loads last session context and open threads |
+| `session_close` | End of session — persists what you learned |
+| `create_learning` | Capture a mistake (scar), success (win), or pattern |
+| `create_decision` | Log an architectural or operational decision with rationale |
+| `list_threads` | See unresolved work carrying over between sessions |
+| `create_thread` | Track something that needs follow-up in a future session |
+| `help` | Show all available commands |
 
-### Before any task
-- Call `recall` with a brief description of what you're about to do
-- Review any scars that surface — they're warnings from past experience
-- Acknowledge relevant scars before proceeding
+## Session end
 
-### At session start
-- Call `session_start` to load context from the last session
-- Review open threads from the previous session
+On "closing", "done for now", or "wrapping up":
 
-### When mistakes happen
-- If something breaks unexpectedly, suggest creating a scar with `create_learning`
-- Include counter-arguments (why someone might think the mistake is OK)
-- Scars need: title, description, severity, and at least 2 counter_arguments
+1. **Answer these reflection questions** and display to the human:
+   - What broke that you didn't expect?
+   - What took longer than it should have?
+   - What would you do differently next time?
+   - What pattern or approach worked well?
+   - What assumption was wrong?
+   - Which scars did you apply?
+   - What should be captured as institutional memory?
 
-### When things go well
-- If a pattern or approach works particularly well, capture it as a win
-- Wins help replicate success across sessions
+2. **Ask the human**: "Any corrections or additions?" Wait for their response.
 
-### When making decisions
-- For architectural or significant operational decisions, log them with `create_decision`
-- Include what alternatives were considered and why they were rejected
+3. **Write payload** to `.gitmem/closing-payload.json`:
+   ```json
+   {
+     "closing_reflection": {
+       "what_broke": "...",
+       "what_took_longer": "...",
+       "do_differently": "...",
+       "what_worked": "...",
+       "wrong_assumption": "...",
+       "scars_applied": "...",
+       "institutional_memory": "..."
+     },
+     "task_completion": {
+       "started_at": "ISO timestamp",
+       "completed_at": "ISO timestamp",
+       "questions_displayed_at": "ISO timestamp",
+       "reflection_completed_at": "ISO timestamp",
+       "human_asked_at": "ISO timestamp",
+       "human_response_at": "ISO timestamp",
+       "human_response": "human's correction text or empty"
+     },
+     "human_corrections": "",
+     "scars_to_record": [],
+     "learnings_created": [],
+     "open_threads": [],
+     "decisions": []
+   }
+   ```
 
-### At session end
-- On "closing", "done for now", or "wrapping up", call `session_close`
-- Reflect on what worked, what broke, and what to do differently
-- Record which scars you applied during the session
-- **Run tests before pushing** — `npm run test:unit` at minimum
+4. **Call `session_close`** with `session_id` and `close_type: "standard"`
 
-## Tool quick reference
-
-| Tool | Alias | When to use |
-|------|-------|-------------|
-| `recall` | `gitmem-r` | Before any task — check for relevant warnings |
-| `session_start` | `gitmem-ss` | Beginning of session — load context |
-| `session_close` | `gitmem-sc` | End of session — persist learnings |
-| `create_learning` | `gitmem-cl` | After mistakes or successes — capture knowledge |
-| `create_decision` | `gitmem-cd` | When making choices — log the reasoning |
-| `record_scar_usage` | `gitmem-rs` | Track which scars helped |
-| `help` | `gitmem-help` | Show all commands |
-
-## Development Commands
-
-When contributing to GitMem itself:
-
-| Command | Purpose |
-|---------|---------|
-| `npm run build` | Build + run unit tests (fails if tests fail) |
-| `npm run test:unit` | Run Tier 1 unit tests (~2s) |
-| `npm run test:integration` | Run Tier 2 integration tests (requires Docker) |
-| `npm run test:perf` | Run Tier 3 performance benchmarks |
-| `npm run test:e2e` | Run Tier 4 E2E smoke tests (requires Docker) |
-| `npm run test:all` | Run all test tiers |
-| `npx gitmem check` | Quick health check (~5s) |
-| `npx gitmem check --full` | Full diagnostic with benchmarks (~30s) |
-
-**Before pushing:** Always run `npm run test:unit` at minimum.
+For short exploratory sessions (< 30 min, no real work), use `close_type: "quick"` — no questions needed.
+<!-- gitmem:end -->

package/README.md

@@ -1,9 +1,11 @@
 # GitMem
 
-Institutional memory for AI coding agents. Never repeat the same mistake.
+Institutional memory for AI coding agents. Memory that compounds.
 
 GitMem is an [MCP server](https://modelcontextprotocol.io/) that gives your AI coding agent persistent memory across sessions. It remembers mistakes (scars), successes (wins), and architectural decisions — so your agent learns from experience instead of starting from scratch every time.
 
+**[Documentation](https://gitmem.dev)** · **[npm](https://www.npmjs.com/package/gitmem-mcp)** · **[GitHub](https://github.com/nTEG-dev/gitmem)**
+
 ## How It Works
 
 1. **Before each task**, the agent calls `recall` with a plan — GitMem surfaces relevant warnings from past sessions
@@ -24,34 +26,64 @@ Over time, your agent builds institutional memory that prevents repeated mistake
 
 ## Quick Start
 
-### Free Tier (zero config)
+### One command setup
 
 ```bash
-npx gitmem-mcp init
-npx gitmem-mcp configure
+npx gitmem init
 ```
 
-This creates a `.gitmem/` directory with starter scars and prints the MCP config to add to your editor.
+The interactive wizard detects your existing config and sets up everything:
+
+1. Creates `.gitmem/` with 12 starter scars
+2. Adds gitmem to `.mcp.json`
+3. Adds memory instructions to `CLAUDE.md`
+4. Configures tool permissions in `.claude/settings.json`
+5. Installs lifecycle hooks
+6. Updates `.gitignore`
+
+Already have `.mcp.json`, `CLAUDE.md`, or hooks? The wizard merges without destroying your existing config.
+
+```bash
+# Non-interactive (accept all defaults)
+npx gitmem init --yes
+
+# Preview what would change
+npx gitmem init --dry-run
+
+# Set project name
+npx gitmem init --project my-app
+```
 
-Add the config to your project's `.mcp.json` (Claude Code) or IDE settings (Cursor, Windsurf), then copy `CLAUDE.md.template` into your project root. Start coding — memory is active.
+Start Claude Code — memory is active.
 
 ### Pro Tier (with Supabase)
 
+For semantic search and cloud persistence:
+
 1. Create a free Supabase project at [database.new](https://database.new)
-2. `npx gitmem-mcp setup` — copy the SQL output into Supabase SQL Editor
-3. Get an API key for embeddings (OpenAI, OpenRouter, or Ollama)
-4. Set `SUPABASE_URL` and `SUPABASE_SERVICE_ROLE_KEY` as environment variables
-5. `npx gitmem-mcp configure` — generates your MCP config with env vars
-6. `npx gitmem-mcp init` — loads starter scars into Supabase
-7. Copy `CLAUDE.md.template` into your project
-8. Start coding — memory is active!
+2. `npx gitmem setup` — copy the SQL output into Supabase SQL Editor
+3. Set `SUPABASE_URL` and `SUPABASE_SERVICE_ROLE_KEY` as environment variables
+4. `npx gitmem init` — auto-detects pro tier from env vars
+
+### Uninstall
+
+```bash
+npx gitmem uninstall
+```
+
+Cleanly removes gitmem from all config files. Your memory data (`.gitmem/`) is preserved by default.
+
+```bash
+# Also delete .gitmem/ data
+npx gitmem uninstall --all
+```
 
 ## Installation
 
 ### npx (no install required)
 
 ```bash
-npx gitmem-mcp init
+npx gitmem init
 ```
 
 ### Global install
@@ -61,9 +93,9 @@ npm install -g gitmem-mcp
 gitmem init
 ```
 
-### MCP Configuration
+### Manual MCP Configuration
 
-Add to your project's `.mcp.json` (Claude Code) or IDE MCP settings (Cursor, Windsurf):
+If you prefer to configure manually instead of using `npx gitmem init`:
 
 **Free Tier:**
 ```json
@@ -110,19 +142,23 @@ claude mcp list
 
 | Command | Description |
 |---------|-------------|
-| `gitmem init` | Initialize memory — loads starter scars (auto-detects tier) |
+| `gitmem init` | Interactive setup wizard — detects, prompts, merges |
+| `gitmem init --yes` | Non-interactive setup (accept all defaults) |
+| `gitmem init --dry-run` | Preview what would be configured |
+| `gitmem uninstall` | Clean removal of gitmem from project |
+| `gitmem uninstall --all` | Also delete `.gitmem/` data directory |
 | `gitmem setup` | Output SQL for Supabase schema setup (Pro tier) |
 | `gitmem configure` | Generate MCP config for your editor |
 | `gitmem check` | Run diagnostic health check |
 | `gitmem check --full` | Full diagnostic with benchmarks |
-| `gitmem install-hooks` | Install Claude Code hooks plugin |
-| `gitmem uninstall-hooks` | Remove Claude Code hooks plugin |
+| `gitmem install-hooks` | Install Claude Code hooks (standalone) |
+| `gitmem uninstall-hooks` | Remove Claude Code hooks (standalone) |
 | `gitmem server` | Start MCP server (default when no command given) |
 | `gitmem help` | Show help |
 
 ## MCP Tools
 
-GitMem exposes tools via the Model Context Protocol. Your AI agent calls these automatically based on the instructions in `CLAUDE.md.template`.
+GitMem exposes tools via the Model Context Protocol. Your AI agent calls these automatically based on the instructions in `CLAUDE.md`.
 
 ### Core Tools
 
@@ -169,23 +205,18 @@ GitMem tracks four types of institutional knowledge:
 
 All types are searched together when `recall` is called, giving the agent comprehensive context.
 
-## Hooks Plugin
+## Lifecycle Hooks
 
-GitMem includes a Claude Code hooks plugin that automates memory protocols:
+GitMem includes Claude Code hooks that automate memory protocols. These are installed automatically by `npx gitmem init`.
 
 - **SessionStart** — Automatically calls `session_start` when a session begins
 - **PreToolUse** — Reminds the agent to call `recall` before consequential actions
 - **PostToolUse** — Tracks scar acknowledgment
 - **Stop** — Reminds the agent to close sessions properly
 
-Install:
-```bash
-npx gitmem-mcp install-hooks
-```
-
-Uninstall:
+To install hooks standalone (without the full wizard):
 ```bash
-npx gitmem-mcp uninstall-hooks
+npx gitmem install-hooks
 ```
 
 ## Agent Detection