From a9038fd5c611219fb1b2b4622abf6670629930cb Mon Sep 17 00:00:00 2001 From: Tony Casey Date: Fri, 13 Feb 2026 13:42:13 +0000 Subject: [PATCH 1/2] docs: rewrite getting-started.md with current CLI and trailers info MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Full rewrite to match current codebase (8 CLI commands, unified init) - Add Claude Code hooks section with .git-mem.json config example - Add Git Trailers subsection to "How it works" (AI-* trailer details) - Fix sessionStop config key in JSON example - Remove outdated init-mcp standalone section and architecture diagrams - Reorganize: Quick Start → Claude hooks → How it works → MCP → CLI Co-Authored-By: Claude Opus 4.6 --- docs/getting-started.md | 383 ++++++++++++++-------------------------- 1 file changed, 129 insertions(+), 254 deletions(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index 42c3f909..2fa43a28 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,322 +1,197 @@ # Getting Started - Requires Node.js >= 18 and git. After install, two binaries are available: - `git-mem` (also works as `git mem` — git subcommand) - `git-mem-mcp` (MCP server for AI tools) -## CLI Usage - -### Store a memory +## Quick Start ```bash -git mem remember "JWT chosen over sessions for stateless API" \ - --type decision \ - --tags "auth, architecture" \ - --confidence high +npm install -g git-mem +cd your-repo +git-mem init ``` -Options: -- `-c, --commit ` — Attach to specific commit (default: HEAD) -- `-t, --type ` — `decision`, `gotcha`, `convention`, `fact` (default: `fact`) -- `--confidence ` — `verified`, `high`, `medium`, `low` (default: `high`) -- `--lifecycle ` — `permanent`, `project`, `session` (default: `project`) -- `--tags ` — Comma-separated tags - -### Search memories +`init` walks you through setup: +1. Creates `.claude/settings.json` with Claude Code hooks +2. Creates `.git-mem.json` with hook configuration +3. Creates `.mcp.json` for the MCP server +4. Updates `.gitignore` +5. Extracts knowledge from recent commits (if `ANTHROPIC_API_KEY` is set) -```bash -git mem recall "authentication" -git mem recall --type decision --json -``` +--- +## Using Claude? + All of the processes happen automatically through Claude's hook events. -Options: -- `-n, --limit ` — Max results (default: 10) -- `-t, --type ` — Filter by type -- `--since ` — Filter by date -- `--json` — Output as JSON +| Hook | What it does | +|------|-------------| +| **SessionStart** | Loads stored memories into Claude's context on startup | +| **Stop** | Extracts knowledge from commits made during the session | +| **UserPromptSubmit** | Surfaces relevant memories per prompt (disabled by default) | -### Show memories relevant to staged changes +Settings are stored in `.git-mem.json`: -```bash -git add . -git mem context +```json +{ + "hooks": { + "enabled": true, + "sessionStart": { "enabled": true, "memoryLimit": 20 }, + "sessionStop": { "enabled": true, "autoExtract": true, "threshold": 3 }, + "promptSubmit": { "enabled": false, "recordPrompts": false, "surfaceContext": true } + } +} ``` -Extracts keywords from staged file paths and diff content, matches against stored memories, and returns scored results. +--- +## How It Works -Options: -- `-n, --limit ` — Max results (default: 10) -- `--threshold ` — Min relevance score 0-1 (default: 0.1) -- `--json` — Output as JSON +git-mem stores knowledge in two ways: -### Extract knowledge from history +### Git Notes (rich JSON) -```bash -git mem extract --since 2024-01-01 --dry-run -git mem extract --threshold 5 --commit-count 100 -git mem extract --enrich --dry-run --commit-count 10 +Memories are stored as JSON in git notes on `refs/notes/mem`. Each commit can have a note containing an array of memory entities: + +``` +refs/notes/mem + └── → { "memories": [{ id, content, type, confidence, tags, ... }] } ``` -Scores commits by interest (conventional prefixes, decision keywords, diff size, PR merges), then extracts decisions/gotchas/conventions using heuristic patterns. Optionally enrich with LLM analysis for deeper insights. +Notes are: +- **Version controlled** — visible in `git log --notes=refs/notes/mem` +- **Shareable** — push/pull with `git mem sync` +- **Non-invasive** — doesn't modify commits, branches, or working tree -Options: -- `--since ` — Start date (default: 90 days ago) -- `--commit-count ` — Max commits to process -- `--dry-run` — Preview without writing -- `--threshold ` — Interest score threshold (default: 3) -- `--enrich` — Enable LLM enrichment (requires `ANTHROPIC_API_KEY`, see [Environment Variables](#environment-variables)) +### Git Trailers (lightweight metadata) -### Sync memories with remote +When you `remember` on HEAD, git-mem also writes AI-* trailers directly into the commit message: -```bash -git mem sync # push + pull -git mem sync --push # push only -git mem sync --pull # pull only +``` +AI-Decision: JWT over sessions — stateless API, scales horizontally +AI-Confidence: high +AI-Memory-Id: 3bf31da6-86a6-43cc-a1db-2f99da187107 +AI-Tags: auth, architecture ``` -Pushes/pulls `refs/notes/mem` to/from origin. - -### Generate MCP config +Trailers are: +- **Natively queryable** — `git log --grep-reflog` or `git log --trailer` +- **Visible** — show up in `git log`, GitHub, and code review tools +- **Only on new commits** — `extract` writes notes only (no history rewrite) -```bash -git mem init-mcp -``` +--- +## Not using Claude? -Creates a `.mcp.json` in the current directory. Auto-detects global vs local install. +### MCP Tools -Options: -- `--force` — Overwrite existing `.mcp.json` -- `--global` — Force use of globally installed binary +The MCP server (`git-mem-mcp`) exposes git-mem to AI tools over stdio: -## MCP Server Setup +| Tool | Description | +|------|-------------| +| `git_mem_remember` | Store a memory attached to a commit | +| `git_mem_recall` | Search and retrieve stored memories | +| `git_mem_context` | Find memories relevant to staged changes | +| `git_mem_extract` | Scan commit history and extract patterns as memories | -The MCP server exposes git-mem's capabilities to AI coding tools (Claude Code, Cursor, etc.) over stdio using the [Model Context Protocol](https://modelcontextprotocol.io). -### Quick setup +--- -```bash -# If git-mem is installed globally: -git mem init-mcp -``` +## Prefer CLI Commands? -This generates `.mcp.json`: +### init -```json -{ - "mcpServers": { - "git-mem": { - "command": "git-mem-mcp" - } - } -} +```bash +git mem init +git mem init -y --commit-count 50 ``` -### Manual setup +Options: +- `-y, --yes` — Accept defaults without prompting +- `--commit-count ` — Number of commits to extract (default: 30) +- `--hooks` — Install prepare-commit-msg git hook +- `--uninstall-hooks` — Remove the prepare-commit-msg git hook -Add to your `.mcp.json` (or the equivalent config for your AI tool): +### remember -```json -{ - "mcpServers": { - "git-mem": { - "command": "git-mem-mcp" - } - } -} -``` - -Or if using a local (non-global) install: +Store a memory attached to the current commit. -```json -{ - "mcpServers": { - "git-mem": { - "command": "node", - "args": ["/path/to/git-mem/dist/mcp-server.js"] - } - } -} +```bash +git mem remember "JWT chosen over sessions for stateless API" \ + --type decision \ + --tags "auth, architecture" \ + --confidence high ``` -### MCP Tools +Writes to git notes and adds AI-* trailers to HEAD. -| Tool | Description | -|------|-------------| -| `git_mem_remember` | Store a memory (decision, gotcha, convention, fact) attached to a commit | -| `git_mem_recall` | Search and retrieve stored memories | -| `git_mem_context` | Find memories relevant to currently staged changes | -| `git_mem_extract` | Scan commit history, score commits, and extract patterns as memories | - -## How It Works +Options: +- `-c, --commit ` — Attach to specific commit (default: HEAD) +- `-t, --type ` — `decision`, `gotcha`, `convention`, `fact` (default: `fact`) +- `--confidence ` — `verified`, `high`, `medium`, `low` (default: `high`) +- `--lifecycle ` — `permanent`, `project`, `session` (default: `project`) +- `--tags ` — Comma-separated tags -### Memory storage +### recall -Memories are stored as JSON in git notes on `refs/notes/mem`. Each commit can have a note containing an array of memory entities: +Search stored memories. -```text -refs/notes/mem - └── → { "memories": [ { id, content, type, confidence, tags, ... } ] } +```bash +git mem recall "authentication" +git mem recall --type decision --json ``` -This means memories are: -- **Version controlled** — stored in git, visible in `git log --notes=refs/notes/mem` -- **Shareable** — push/pull with `git mem sync` -- **Non-invasive** — doesn't modify commits, branches, or working tree +Options: +- `-n, --limit ` — Max results (default: 10) +- `-t, --type ` — Filter by type +- `--since ` — Filter by date +- `--json` — Output as JSON -### How `remember` stores data - -```text -┌──────────────────┐ -│ git mem remember │ -│ "Use JWT auth" │ -└────────┬─────────┘ - │ - ▼ -┌──────────────────┐ ┌─────────────────────────┐ -│ MemoryService │────▶│ MemoryRepository │ -│ (build entity) │ │ (read existing notes, │ -└──────────────────┘ │ append, write back) │ - └────────┬────────────────┘ - │ - ▼ - ┌─────────────────────────┐ - │ NotesService │ - │ git notes --ref= │ - │ refs/notes/mem │ - │ add -f -m │ - │ │ - └─────────────────────────┘ - │ - ▼ - ┌─────────────────────────┐ - │ Git Object Store │ - │ │ - │ commit abc123 │ - │ └── note (refs/notes/ │ - │ mem): {memories: │ - │ [{id, content, │ - │ type, ...}]} │ - └─────────────────────────┘ -``` +### extract -### How `extract` captures knowledge from history - -```text -┌──────────────────────┐ -│ git mem extract │ -└────────┬─────────────┘ - │ - ▼ -┌──────────────────────┐ ┌─────────────────────────┐ -│ ExtractService │────▶│ GitTriageService │ -│ │ │ (score each commit by │ -│ │ │ conventional prefixes, │ -│ │ │ decision keywords, │ -│ │ │ diff size, PR merges) │ -│ │ └────────┬────────────────┘ -│ │ │ -│ │ ▼ -│ │ ┌─────────────────────────┐ -│ │────▶│ HeuristicPatterns │ -│ │ │ (regex extraction of │ -│ │ │ decisions, gotchas, │ -│ │ │ conventions from │ -│ │ │ commit messages) │ -│ │ └────────┬────────────────┘ -│ │ │ -│ │ ▼ -│ │ ┌─────────────────────────┐ -│ │────▶│ MemoryRepository │ -│ │ │ (write extracted facts │ -└──────────────────────┘ │ as notes on commits) │ - └─────────────────────────┘ -``` +Scan commit history, score commits by interest, and extract decisions/gotchas/conventions as memories. -### How AI tools use git-mem via MCP - -```text -┌───────────────────┐ -│ AI Coding Tool │ -│ (Claude Code, │ -│ Cursor, etc.) │ -└────────┬──────────┘ - │ JSON-RPC 2.0 over stdio - │ - ▼ -┌───────────────────┐ -│ git-mem-mcp │ -│ (MCP Server) │ -│ │ -│ Tools: │ -│ ┌──────────────┐ │ -│ │ remember │ │ -│ │ recall │ │ -│ │ context │ │ -│ │ extract │ │ -│ └──────────────┘ │ -└────────┬──────────┘ - │ Spawns fresh service - │ instances per call - ▼ -┌───────────────────┐ -│ Application │ -│ Services │ -│ (MemoryService, │ -│ ContextService, │ -│ ExtractService) │ -└────────┬──────────┘ - │ - ▼ -┌───────────────────┐ -│ Git CLI │ -│ (git notes, │ -│ git log, etc.) │ -└────────┬──────────┘ - │ - ▼ -┌───────────────────┐ -│ .git/ │ -│ refs/notes/mem │ -│ (memory data) │ -└───────────────────┘ +```bash +git mem extract --since 2024-01-01 --dry-run +git mem extract --threshold 5 --commit-count 100 +git mem extract --enrich --dry-run --commit-count 10 ``` -## Environment Variables +Options: +- `--since ` — Start date (default: 90 days ago) +- `--commit-count ` — Max commits to process +- `--dry-run` — Preview without writing +- `--threshold ` — Interest score threshold (default: 3) +- `--enrich` — Enable LLM enrichment (requires `ANTHROPIC_API_KEY`) -| Variable | Required | Description | -|---------------------|----------|--------------------------------------------------------------------------------------------------------------------------| -| `ANTHROPIC_API_KEY` | Only for `--enrich` | Anthropic API key for LLM enrichment during extract. Get one at [console.anthropic.com](https://console.anthropic.com/). | +### context -Copy `.env.example` to `.env` and fill in values: +Show memories relevant to staged changes. ```bash -cp .env.example .env +git add . +git mem context ``` -If `--enrich` is used without an API key, git-mem prints a warning and falls back to heuristic extraction only. +Options: +- `-n, --limit ` — Max results (default: 10) +- `--threshold ` — Min relevance score 0-1 (default: 0.1) +- `--json` — Output as JSON + +### sync -## Development +Push/pull memory refs to/from origin. ```bash -git clone https://github.com/TonyCasey/git-mem.git -cd git-mem -npm install -npm run build +git mem sync # push + pull +git mem sync --push # push only +git mem sync --pull # pull only ``` -```bash -npm test # all tests -npm run test:unit # unit tests only -npm run test:integration # integration tests only -# Run a single test: -node --import tsx --test tests/unit/application/services/MemoryService.test.ts -``` +## Environment Variables -```bash -# Rebuild and reinstall globally (for manual testing): -./scripts/reinstall-global.sh -``` +| Variable | Required | Description | +|----------|----------|-------------| +| `ANTHROPIC_API_KEY` | Only for `--enrich` | Anthropic API key for LLM enrichment during extract. Get one at [console.anthropic.com](https://console.anthropic.com/). | + +If `--enrich` is used without an API key, git-mem falls back to heuristic extraction only. From 83a118bd945cfdd292cc5a1352d26954f4be2f08 Mon Sep 17 00:00:00 2001 From: Tony Casey Date: Fri, 13 Feb 2026 13:47:18 +0000 Subject: [PATCH 2/2] docs: address review - markdown lint, --no-trailers flag, init default - Add blank lines around headings (MD022) - Add text language tag to fenced code blocks (MD040) - Document --no-trailers flag on remember command - Fix init --commit-count default to 100 (matches src/cli.ts) Co-Authored-By: Claude Opus 4.6 --- docs/getting-started.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index 2fa43a28..a91908d9 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -22,8 +22,10 @@ git-mem init 5. Extracts knowledge from recent commits (if `ANTHROPIC_API_KEY` is set) --- + ## Using Claude? - All of the processes happen automatically through Claude's hook events. + +All of the processes happen automatically through Claude's hook events. | Hook | What it does | |------|-------------| @@ -45,6 +47,7 @@ Settings are stored in `.git-mem.json`: ``` --- + ## How It Works git-mem stores knowledge in two ways: @@ -53,7 +56,7 @@ git-mem stores knowledge in two ways: Memories are stored as JSON in git notes on `refs/notes/mem`. Each commit can have a note containing an array of memory entities: -``` +```text refs/notes/mem └── → { "memories": [{ id, content, type, confidence, tags, ... }] } ``` @@ -67,7 +70,7 @@ Notes are: When you `remember` on HEAD, git-mem also writes AI-* trailers directly into the commit message: -``` +```text AI-Decision: JWT over sessions — stateless API, scales horizontally AI-Confidence: high AI-Memory-Id: 3bf31da6-86a6-43cc-a1db-2f99da187107 @@ -80,6 +83,7 @@ Trailers are: - **Only on new commits** — `extract` writes notes only (no history rewrite) --- + ## Not using Claude? ### MCP Tools @@ -107,7 +111,7 @@ git mem init -y --commit-count 50 Options: - `-y, --yes` — Accept defaults without prompting -- `--commit-count ` — Number of commits to extract (default: 30) +- `--commit-count ` — Number of commits to extract (default: 100) - `--hooks` — Install prepare-commit-msg git hook - `--uninstall-hooks` — Remove the prepare-commit-msg git hook @@ -130,6 +134,7 @@ Options: - `--confidence ` — `verified`, `high`, `medium`, `low` (default: `high`) - `--lifecycle ` — `permanent`, `project`, `session` (default: `project`) - `--tags ` — Comma-separated tags +- `--no-trailers` — Skip writing AI-* trailers to the commit message ### recall