gitmem-mcp 0.2.0 → 1.0.1

package/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.0] - 2026-02-10
+
+### Added
+- **Hooks plugin bundled**: `gitmem install-hooks` / `uninstall-hooks` CLI commands (OD-605, OD-606)
+- **CLI `check` command wired**: `gitmem check` now reachable from CLI (was defined but unreachable)
+- **Fresh-install E2E tests**: 16 integration tests covering CLI commands, hooks, and MCP server lifecycle (OD-607)
+- **README rewrite**: External-developer-facing docs with no internal jargon (OD-608)
+- **CONTRIBUTING.md**: Dev setup, testing tiers, and PR guidelines
+- **First public npm release** (OD-609)
+
+### Changed
+- Package name standardized to `gitmem-mcp` for npm
+- `gitmem configure` output uses `gitmem-mcp` (matching npm package name)
+- Removed internal project defaults from CLI commands
+
 ## [0.2.0] - 2026-02-08
 
 ### Added
@@ -42,6 +57,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Cache management (status, flush, health)
 - Agent identity detection
 
-[Unreleased]: https://github.com/nTEG-dev/gitmem/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/nTEG-dev/gitmem/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/nTEG-dev/gitmem/compare/v0.2.0...v1.0.0
 [0.2.0]: https://github.com/nTEG-dev/gitmem/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/nTEG-dev/gitmem/releases/tag/v0.1.0

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,86 +1,121 @@
 # GitMem
 
-Institutional memory for AI coding agents. Never repeat the same mistake.
+Institutional memory for AI coding agents. Memory that compounds.
 
-## Features
+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.
 
-- **Predict**: Check institutional memory for relevant learnings before taking action (core GitMem MVP tool)
-- **Session Start**: Initialize session, detect agent identity, load last session context, retrieve relevant learnings, load recent decisions
-- **Session Close**: Persist session with compliance validation (standard/quick/autonomous close types)
-- **Learning Capture**: Create scars, wins, patterns, and anti-patterns in institutional memory
-- **Decision Logging**: Log architectural and operational decisions
-- **Scar Usage Tracking**: Track scar application for effectiveness measurement
-- **[Threads](docs/threads.md)**: Persistent work items that carry across sessions — create, list, resolve
-- **[Doc-Debt Tracking](docs/doc-debt-tracking.md)**: Detect when decisions outpace documentation updates
+**[Documentation](https://gitmem.dev)** · **[npm](https://www.npmjs.com/package/gitmem-mcp)** · **[GitHub](https://github.com/nTEG-dev/gitmem)**
 
-### Learning Types
+## How It Works
 
-GitMem tracks **all learning types**:
-- **Scars** — Failures to avoid (critical institutional memory)
-- **Patterns** — Neutral observations and recurring patterns
-- **Wins** — Successes to replicate
-- **Anti-patterns** — Known bad approaches
+1. **Before each task**, the agent calls `recall` with a plan — GitMem surfaces relevant warnings from past sessions
+2. **When mistakes happen**, the agent captures them as "scars" — failures with context and counter-arguments
+3. **When things go well**, the agent captures wins and patterns to replicate
+4. **At session close**, the agent reflects on what worked, what broke, and what to do differently
 
-All learning types use the same vector search infrastructure and are queried together for comprehensive institutional context.
+Over time, your agent builds institutional memory that prevents repeated mistakes and reinforces good patterns.
+
+### Two Tiers
+
+| | Free Tier | Pro Tier |
+|---|-----------|----------|
+| **Storage** | Local `.gitmem/` directory | Supabase (PostgreSQL + pgvector) |
+| **Search** | Keyword matching | Semantic vector search |
+| **Setup** | Zero config | Supabase project + embedding API key |
+| **Best for** | Solo projects | Teams, cross-project memory |
 
 ## Quick Start
 
-### Free Tier (zero config)
+### One command setup
 
 ```bash
 npx gitmem init
-npx gitmem configure
 ```
 
-Copy `CLAUDE.md.template` into your project, then start coding — memory is active.
+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
+```
+
+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 setup` — copy the SQL output into Supabase SQL Editor
-3. Get an API key for embeddings (OpenAI, OpenRouter, or Ollama)
-4. `npx gitmem configure` — generates your `.mcp.json` config
-5. `npx gitmem init` — loads starter scars into Supabase
-6. Copy `CLAUDE.md.template` into your project
-7. Start coding — memory is active!
+3. Set `SUPABASE_URL` and `SUPABASE_SERVICE_ROLE_KEY` as environment variables
+4. `npx gitmem init` — auto-detects pro tier from env vars
 
-## Installation
+### Uninstall
+
+```bash
+npx gitmem uninstall
+```
 
-### npm (recommended)
+Cleanly removes gitmem from all config files. Your memory data (`.gitmem/`) is preserved by default.
 
 ```bash
-npm install gitmem
+# Also delete .gitmem/ data
+npx gitmem uninstall --all
 ```
 
-### npx (no install)
+## Installation
+
+### npx (no install required)
 
 ```bash
 npx gitmem init
 ```
 
-### MCP Registration
+### Global install
 
-Add to your project's `.mcp.json` (Claude Code) or IDE settings (Cursor, Windsurf):
+```bash
+npm install -g gitmem-mcp
+gitmem init
+```
 
+### Manual MCP Configuration
+
+If you prefer to configure manually instead of using `npx gitmem init`:
+
+**Free Tier:**
 ```json
 {
   "mcpServers": {
     "gitmem": {
       "command": "npx",
-      "args": ["-y", "gitmem"]
+      "args": ["-y", "gitmem-mcp"]
     }
   }
 }
 ```
 
-For Pro tier, add environment variables:
-
+**Pro Tier:**
 ```json
 {
   "mcpServers": {
     "gitmem": {
       "command": "npx",
-      "args": ["-y", "gitmem"],
+      "args": ["-y", "gitmem-mcp"],
       "env": {
         "SUPABASE_URL": "https://your-project.supabase.co",
         "SUPABASE_SERVICE_ROLE_KEY": "eyJ...",
@@ -91,131 +126,125 @@ For Pro tier, add environment variables:
 }
 ```
 
+Alternative embedding providers (set instead of `OPENAI_API_KEY`):
+- `OPENROUTER_API_KEY` — OpenRouter (multiple models)
+- `OLLAMA_URL` — Local Ollama instance (no API key needed)
+
 ### Verify
 
 ```bash
+# Claude Code
 claude mcp list
-# Should show: gitmem: ✓ Connected
+# Should show: gitmem: connected
 ```
 
 ## CLI Commands
 
 | Command | Description |
 |---------|-------------|
-| `gitmem init` | Initialize memory (loads starter scars) |
-| `gitmem setup` | Output SQL for Supabase schema setup |
-| `gitmem configure` | Generate `.mcp.json` config |
-| `gitmem server` | Start MCP server (default) |
+| `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 (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
 
-### `predict`
-
-Check institutional memory for relevant learnings before taking action.
-
-**Parameters:**
-- `plan` (required) - What you're about to do (e.g., "deploy to production")
-- `project?` - Project scope (default: "orchestra_dev")
-- `match_count?` - Number of learnings to return (default: 3)
-
-### `session_start`
-
-Initialize session and load institutional context.
-
-**Parameters:**
-- `agent_identity?` - Override agent identity (auto-detects if not provided)
-- `linear_issue?` - Current Linear issue identifier
-- `project?` - Project scope
+GitMem exposes tools via the Model Context Protocol. Your AI agent calls these automatically based on the instructions in `CLAUDE.md`.
 
-### `session_close`
+### Core Tools
 
-Persist session with compliance validation.
+| Tool | Purpose |
+|------|---------|
+| `recall` | Check memory for relevant warnings before taking action |
+| `session_start` | Initialize session, load context from last session |
+| `session_close` | Persist session with reflection |
+| `create_learning` | Capture scars (failures), wins (successes), or patterns |
+| `create_decision` | Log architectural/operational decisions |
+| `record_scar_usage` | Track which scars were applied |
+| `search` | Search institutional memory (exploration, no side effects) |
+| `log` | List recent learnings chronologically |
 
-**Parameters:**
-- `session_id` (required) - From session_start
-- `close_type` (required) - "standard" | "quick" | "autonomous"
-- `closing_reflection?` - Reflection answers (required for standard)
-- `human_corrections?` - Human additions (required for standard)
+### Thread Tools
 
-### `create_learning`
+Threads are persistent work items that carry across sessions.
 
-Create scar, win, or pattern entry.
+| Tool | Purpose |
+|------|---------|
+| `list_threads` | List open threads |
+| `create_thread` | Create a new thread |
+| `resolve_thread` | Mark a thread as resolved |
 
-**Parameters:**
-- `learning_type` (required) - "scar" | "win" | "pattern"
-- `title`, `description` (required)
-- `severity?` - For scars: "critical" | "high" | "medium" | "low"
-- `counter_arguments?` - For scars: min 2 required
+### Pro Tier Tools
 
-### `create_decision`
+Available when Supabase is configured:
 
-Log decision to institutional memory.
+| Tool | Purpose |
+|------|---------|
+| `analyze` | Session analytics and pattern detection |
+| `prepare_context` | Multi-agent context preparation |
+| `absorb_observations` | Multi-agent observation absorption |
+| Cache tools | `cache_status`, `cache_flush`, `cache_health` |
 
-**Parameters:**
-- `title`, `decision`, `rationale` (required)
-- `alternatives_considered?` - Rejected options
-- `docs_affected?` - Docs/files affected by this decision (relative paths from repo root). Used for [doc-debt tracking](docs/doc-debt-tracking.md).
-- `personas_involved?` - Team personas involved
-- `linear_issue?` - Associated issue
+## Learning Types
 
-### `record_scar_usage`
+GitMem tracks four types of institutional knowledge:
 
-Track scar application.
+- **Scars** — Failures to avoid. Include severity and counter-arguments (why someone might think the mistake is OK). These are the core of GitMem.
+- **Wins** — Successes to replicate. Capture what worked and why.
+- **Patterns** — Neutral observations and recurring approaches.
+- **Anti-patterns** — Known bad approaches to flag.
 
-**Parameters:**
-- `scar_id` (required) - Learning UUID
-- `reference_type` (required) - "explicit" | "implicit" | "acknowledged" | "refuted" | "none"
-- `reference_context` (required) - How scar was applied
+All types are searched together when `recall` is called, giving the agent comprehensive context.
 
-### `list_threads`
+## Lifecycle Hooks
 
-List open threads (persistent work items across sessions). See [threads docs](docs/threads.md).
+GitMem includes Claude Code hooks that automate memory protocols. These are installed automatically by `npx gitmem init`.
 
-**Parameters:**
-- `status?` - Filter: "open" (default) or "resolved"
-- `include_resolved?` - Include recently resolved threads
+- **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
 
-### `create_thread`
-
-Create a new open thread.
-
-**Parameters:**
-- `text` (required) - Thread description
-
-### `resolve_thread`
-
-Mark a thread as resolved.
-
-**Parameters:**
-- `thread_id?` - Exact thread ID (e.g., "t-a1b2c3d4")
-- `text_match?` - Case-insensitive substring match
-- `resolution_note?` - Brief resolution explanation
+To install hooks standalone (without the full wizard):
+```bash
+npx gitmem install-hooks
+```
 
 ## Agent Detection
 
-Automatically detects agent identity based on:
-- `CLAUDE_CODE_ENTRYPOINT` environment variable
-- Docker container presence (`/.dockerenv`)
-- Hostname
+GitMem automatically detects the AI agent identity based on environment:
 
-| ENTRYPOINT | Docker | Identity |
-|------------|--------|----------|
-| cli | YES | CLI |
-| cli | NO | CODA-1 |
-| claude-desktop | NO | DAC |
-| (empty) | (has fs) | Brain_Local |
-| (empty) | (no fs) | Brain_Cloud |
+| Environment | Identity |
+|-------------|----------|
+| Claude Code in Docker | CLI |
+| Claude Desktop app | DAC |
+| Claude.ai with filesystem | Brain_Local |
+| Claude.ai without filesystem | Brain_Cloud |
+
+Override with `agent_identity` parameter in `session_start`.
 
 ## Development
 
 ```bash
+git clone https://github.com/nTEG-dev/gitmem.git
+cd gitmem
 npm install
-npm run build
-npm run dev  # Watch mode
-npm test
+npm run build    # Compile TypeScript + run unit tests
+npm run dev      # Watch mode
+npm test         # Run unit tests
 ```
 
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing tiers, and PR guidelines.
+
 ## License
 
-MIT
+MIT — see [LICENSE](LICENSE).