gitmem-mcp 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.2] - 2026-02-15
+
+### Fixed
+- **Free tier crash**: `markSessionSuperseded` called Supabase without `hasSupabase()` guard
+- **Session close UX**: Write health block only shown when failures exist (was always visible)
+- **E2E test suite**: Updated for display protocol changes (session_id extraction, display format assertions, recall display text, CLAUDE.md template wording)
+
 ## [1.0.0] - 2026-02-10
 
 ### Added

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,71 +1,93 @@
-# GitMem
+<p align="center">
+  <img src="assets/banner.svg" alt="GitMem — Institutional memory for AI coding agents" width="700" />
+</p>
 
-Institutional memory for AI coding agents. Never repeat the same mistake.
+<p align="center">
+  <a href="https://www.npmjs.com/package/gitmem-mcp"><img src="https://img.shields.io/npm/v/gitmem-mcp?style=flat-square&color=ed1e25&label=npm" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/gitmem-mcp"><img src="https://img.shields.io/npm/dm/gitmem-mcp?style=flat-square&color=333333&label=downloads" alt="npm downloads" /></a>
+  <a href="https://github.com/nTEG-dev/gitmem/blob/main/LICENSE"><img src="https://img.shields.io/github/license/nTEG-dev/gitmem?style=flat-square&color=ed1e25" alt="MIT License" /></a>
+  <a href="https://github.com/nTEG-dev/gitmem/actions"><img src="https://img.shields.io/github/actions/workflow/status/nTEG-dev/gitmem/deploy-docs.yml?style=flat-square&color=333333&label=build" alt="Build" /></a>
+  <img src="https://img.shields.io/badge/node-%3E%3D22-ed1e25?style=flat-square" alt="Node.js >= 22" />
+</p>
 
-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.
+<p align="center">
+  <a href="https://gitmem.dev/docs"><strong>Documentation</strong></a> &middot;
+  <a href="https://www.npmjs.com/package/gitmem-mcp"><strong>npm</strong></a> &middot;
+  <a href="https://gitmem.dev/docs/getting-started"><strong>Getting Started</strong></a> &middot;
+  <a href="https://gitmem.dev/docs/tools"><strong>Tool Reference</strong></a>
+</p>
 
-## How It Works
+---
 
-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
+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 decisions — so your agent learns from experience instead of starting from scratch every time.
 
-Over time, your agent builds institutional memory that prevents repeated mistakes and reinforces good patterns.
+Works with **Claude Code**, **Claude Desktop**, **Cursor**, and any MCP-compatible client.
 
-### Two Tiers
+## Quick Start
 
-| | 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 |
+```bash
+npx gitmem init
+```
 
-## Quick Start
+One command. The wizard sets up everything:
+- `.gitmem/` directory with 12 starter scars
+- `.mcp.json` with gitmem server entry
+- `CLAUDE.md` with memory protocol instructions
+- `.claude/settings.json` with tool permissions
+- Lifecycle hooks for automatic session management
+- `.gitignore` updated
 
-### Free Tier (zero config)
+Already have existing config? The wizard merges without destroying anything. Re-running is safe.
 
 ```bash
-npx gitmem-mcp init
-npx gitmem-mcp configure
+npx gitmem init --yes       # Non-interactive
+npx gitmem init --dry-run   # Preview changes
 ```
 
-This creates a `.gitmem/` directory with starter scars and prints the MCP config to add to your editor.
+## How It Works
 
-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.
+```
+recall  -->  work  -->  learn  -->  close  -->  recall  -->  ...
+```
 
-### Pro Tier (with Supabase)
+1. **Recall** — Before acting, the agent checks memory for relevant lessons from past sessions
+2. **Work** — The agent does the task, applying past lessons automatically
+3. **Learn** — Mistakes become **scars**, successes become **wins**, strategies become **patterns**
+4. **Close** — Session reflection persists context for next time
 
-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!
+Every scar includes **counter-arguments** — reasons why someone might reasonably ignore it. This prevents memory from becoming a pile of rigid rules.
 
-## Installation
+## What Gets Remembered
 
-### npx (no install required)
+| Type | Purpose | Example |
+|------|---------|---------|
+| **Scars** | Mistakes to avoid | "Always validate UUID format before DB lookup" |
+| **Wins** | Approaches that worked | "Parallel agent spawning cut review time by 60%" |
+| **Patterns** | Reusable strategies | "5-tier test pyramid for MCP servers" |
+| **Decisions** | Architectural choices with rationale | "Chose JWT over session cookies for stateless auth" |
+| **Threads** | Unfinished work that carries across sessions | "Rate limiting still needs implementation" |
 
-```bash
-npx gitmem-mcp init
-```
+## Key Features
 
-### Global install
+- **Automatic Recall** — Scars surface before the agent takes similar actions
+- **Session Continuity** — Context, threads, and rapport carry across sessions
+- **Closing Ceremony** — Structured reflection captures what broke, what worked, and what to do differently
+- **23 MCP Tools** — Full toolkit for memory management, search, threads, and multi-agent coordination
+- **Zero Config** — `npx gitmem init` and you're running
+- **Non-Destructive** — Merges with your existing `.mcp.json`, `CLAUDE.md`, and hooks
 
-```bash
-npm install -g gitmem-mcp
-gitmem init
-```
+## Supported Clients
 
-### MCP Configuration
+| Client | Setup |
+|--------|-------|
+| **Claude Code** | `npx gitmem init` (auto-detected) |
+| **Claude Desktop** | `npx gitmem init` or add to `claude_desktop_config.json` |
+| **Cursor** | `npx gitmem init` or add to `.cursor/mcp.json` |
+| **Any MCP client** | Add `npx -y gitmem-mcp` as an MCP server |
 
-Add to your project's `.mcp.json` (Claude Code) or IDE MCP settings (Cursor, Windsurf):
+<details>
+<summary><strong>Manual MCP configuration</strong></summary>
 
-**Free Tier:**
 ```json
 {
   "mcpServers": {
@@ -77,129 +99,24 @@ Add to your project's `.mcp.json` (Claude Code) or IDE MCP settings (Cursor, Win
 }
 ```
 
-**Pro Tier:**
-```json
-{
-  "mcpServers": {
-    "gitmem": {
-      "command": "npx",
-      "args": ["-y", "gitmem-mcp"],
-      "env": {
-        "SUPABASE_URL": "https://your-project.supabase.co",
-        "SUPABASE_SERVICE_ROLE_KEY": "eyJ...",
-        "OPENAI_API_KEY": "sk-..."
-      }
-    }
-  }
-}
-```
-
-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
-```
+</details>
 
 ## CLI Commands
 
 | Command | Description |
 |---------|-------------|
-| `gitmem init` | Initialize memory — loads starter scars (auto-detects tier) |
-| `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 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`.
-
-### Core Tools
-
-| 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 |
-
-### Thread Tools
-
-Threads are persistent work items that carry across sessions.
-
-| Tool | Purpose |
-|------|---------|
-| `list_threads` | List open threads |
-| `create_thread` | Create a new thread |
-| `resolve_thread` | Mark a thread as resolved |
-
-### Pro Tier Tools
-
-Available when Supabase is configured:
-
-| 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` |
-
-## Learning Types
-
-GitMem tracks four types of institutional knowledge:
-
-- **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.
-
-All types are searched together when `recall` is called, giving the agent comprehensive context.
-
-## Hooks Plugin
-
-GitMem includes a Claude Code hooks plugin that automates memory protocols:
-
-- **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:
-```bash
-npx gitmem-mcp uninstall-hooks
-```
-
-## Agent Detection
+| `npx gitmem init` | Interactive setup wizard |
+| `npx gitmem init --yes` | Non-interactive setup |
+| `npx gitmem init --dry-run` | Preview changes |
+| `npx gitmem uninstall` | Clean removal (preserves `.gitmem/` data) |
+| `npx gitmem uninstall --all` | Full removal including data |
+| `npx gitmem check` | Diagnostic health check |
 
-GitMem automatically detects the AI agent identity based on environment:
+## Pro Tier — Coming Soon
 
-| Environment | Identity |
-|-------------|----------|
-| Claude Code in Docker | CLI |
-| Claude Desktop app | DAC |
-| Claude.ai with filesystem | Brain_Local |
-| Claude.ai without filesystem | Brain_Cloud |
+The free tier gives you everything you need for solo projects. **Pro** will add cloud storage (Supabase), semantic vector search, cross-machine sync, team shared memory, and session transcripts.
 
-Override with `agent_identity` parameter in `session_start`.
+[Join the mailing list](https://gitmem.dev) to get notified when Pro launches.
 
 ## Development
 
@@ -207,12 +124,11 @@ Override with `agent_identity` parameter in `session_start`.
 git clone https://github.com/nTEG-dev/gitmem.git
 cd gitmem
 npm install
-npm run build    # Compile TypeScript + run unit tests
-npm run dev      # Watch mode
-npm test         # Run unit tests
+npm run build
+npm test
 ```
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing tiers, and PR guidelines.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for full development setup.
 
 ## License