gitmem-mcp 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+All notable changes to gitmem will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-02-08
+
+### Added
+- **Full monorepo sync**: Standalone repo is now source of truth (Option A — OD-574, GIT-1)
+- **Zod schemas**: 14 schema files for all tool parameter validation (`src/schemas/`)
+- **Diagnostics suite**: Health checks, channel instrumentation, anonymization (`src/diagnostics/`)
+- **Single source of truth constants**: Closing questions defined once (`src/constants/closing-questions.ts`)
+- **Multi-agent tools**: `prepare_context` and `absorb_observations` (GitMem v2 Phase 1-2)
+- **Tool definitions module**: Centralized tool registration (`src/tools/definitions.ts`)
+- **Commands module**: `gitmem check` CLI health diagnostics (`src/commands/check.ts`)
+- **Full test suite**: 354+ unit tests across 20 test files, plus integration, e2e, and performance benchmarks
+- **Vitest configs**: Separate configs for unit, integration, e2e, and performance tests
+- **Compliance validator warnings**: Q3/Q5 substantive answers warn if no learnings created
+
+### Fixed
+- **Critical**: GitMem now loads ALL learning types (scars, patterns, wins, anti-patterns) instead of just scars
+- Closing reflection schema now includes Q7 (`institutional_memory_items`) field
+
+### Changed
+- `build` script now runs unit tests after compilation (`tsc && npm run test:unit`)
+- Version bumped to 0.2.0 to reflect full feature parity with monorepo
+
+## [0.1.0] - 2026-02-03
+
+### Added
+- Initial MCP server implementation
+- Predict tool (scar search with temporal decay)
+- Session lifecycle (session_start, session_close)
+- Learning capture (scars, wins, patterns)
+- Decision logging
+- Scar usage tracking
+- Local vector search with OpenRouter embeddings
+- Cache management (status, flush, health)
+- Agent identity detection
+
+[Unreleased]: https://github.com/nTEG-dev/gitmem/compare/v0.2.0...HEAD
+[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

@@ -0,0 +1,65 @@
+# GitMem — Institutional 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.
+
+## Automatic behaviors
+
+When working on this project, follow these memory protocols:
+
+### 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
+
+### At session start
+- Call `session_start` to load context from the last session
+- Review open threads from the previous session
+
+### 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
+
+### When things go well
+- If a pattern or approach works particularly well, capture it as a win
+- Wins help replicate success across sessions
+
+### When making decisions
+- For architectural or significant operational decisions, log them with `create_decision`
+- Include what alternatives were considered and why they were rejected
+
+### 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
+
+## 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.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nTEG Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,221 @@
+# GitMem
+
+Institutional memory for AI coding agents. Never repeat the same mistake.
+
+## Features
+
+- **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
+
+### Learning Types
+
+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
+
+All learning types use the same vector search infrastructure and are queried together for comprehensive institutional context.
+
+## Quick Start
+
+### Free Tier (zero config)
+
+```bash
+npx gitmem init
+npx gitmem configure
+```
+
+Copy `CLAUDE.md.template` into your project, then start coding — memory is active.
+
+### Pro Tier (with Supabase)
+
+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!
+
+## Installation
+
+### npm (recommended)
+
+```bash
+npm install gitmem
+```
+
+### npx (no install)
+
+```bash
+npx gitmem init
+```
+
+### MCP Registration
+
+Add to your project's `.mcp.json` (Claude Code) or IDE settings (Cursor, Windsurf):
+
+```json
+{
+  "mcpServers": {
+    "gitmem": {
+      "command": "npx",
+      "args": ["-y", "gitmem"]
+    }
+  }
+}
+```
+
+For Pro tier, add environment variables:
+
+```json
+{
+  "mcpServers": {
+    "gitmem": {
+      "command": "npx",
+      "args": ["-y", "gitmem"],
+      "env": {
+        "SUPABASE_URL": "https://your-project.supabase.co",
+        "SUPABASE_SERVICE_ROLE_KEY": "eyJ...",
+        "OPENAI_API_KEY": "sk-..."
+      }
+    }
+  }
+}
+```
+
+### Verify
+
+```bash
+claude mcp list
+# 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 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
+
+### `session_close`
+
+Persist session with compliance validation.
+
+**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)
+
+### `create_learning`
+
+Create scar, win, or pattern entry.
+
+**Parameters:**
+- `learning_type` (required) - "scar" | "win" | "pattern"
+- `title`, `description` (required)
+- `severity?` - For scars: "critical" | "high" | "medium" | "low"
+- `counter_arguments?` - For scars: min 2 required
+
+### `create_decision`
+
+Log decision to institutional memory.
+
+**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
+
+### `record_scar_usage`
+
+Track scar application.
+
+**Parameters:**
+- `scar_id` (required) - Learning UUID
+- `reference_type` (required) - "explicit" | "implicit" | "acknowledged" | "refuted" | "none"
+- `reference_context` (required) - How scar was applied
+
+### `list_threads`
+
+List open threads (persistent work items across sessions). See [threads docs](docs/threads.md).
+
+**Parameters:**
+- `status?` - Filter: "open" (default) or "resolved"
+- `include_resolved?` - Include recently resolved threads
+
+### `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
+
+## Agent Detection
+
+Automatically detects agent identity based on:
+- `CLAUDE_CODE_ENTRYPOINT` environment variable
+- Docker container presence (`/.dockerenv`)
+- Hostname
+
+| ENTRYPOINT | Docker | Identity |
+|------------|--------|----------|
+| cli | YES | CLI |
+| cli | NO | CODA-1 |
+| claude-desktop | NO | DAC |
+| (empty) | (has fs) | Brain_Local |
+| (empty) | (no fs) | Brain_Cloud |
+
+## Development
+
+```bash
+npm install
+npm run build
+npm run dev  # Watch mode
+npm test
+```
+
+## License
+
+MIT