From 7363ee5bfac981a4818e73369f182f11ed983fa3 Mon Sep 17 00:00:00 2001 From: Tony Casey <26551393+TonyCasey@users.noreply.github.com> Date: Fri, 13 Feb 2026 13:50:44 +0000 Subject: [PATCH 1/2] docs: rewrite getting-started.md with current CLI and trailers info (#44) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs: rewrite getting-started.md with current CLI and trailers info - 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: 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 --------- Co-authored-by: Claude Opus 4.6 AI-Fact: Changed initial commit count AI-Confidence: high AI-Memory-Id: a0b9475f-6014-477e-ad81-584f7c72fd61 --- docs/getting-started.md | 384 ++++++++++++++-------------------------- 1 file changed, 132 insertions(+), 252 deletions(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index 42c3f909..a91908d9 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,322 +1,202 @@ # 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 +`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) -### Search memories +--- -```bash -git mem recall "authentication" -git mem recall --type decision --json -``` +## Using Claude? -Options: -- `-n, --limit ` — Max results (default: 10) -- `-t, --type ` — Filter by type -- `--since ` — Filter by date -- `--json` — Output as JSON - -### Show memories relevant to staged changes - -```bash -git add . -git mem context -``` - -Extracts keywords from staged file paths and diff content, matches against stored memories, and returns scored results. +All of the processes happen automatically through Claude's hook events. -Options: -- `-n, --limit ` — Max results (default: 10) -- `--threshold ` — Min relevance score 0-1 (default: 0.1) -- `--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) | -### Extract knowledge from history +Settings are stored in `.git-mem.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 +```json +{ + "hooks": { + "enabled": true, + "sessionStart": { "enabled": true, "memoryLimit": 20 }, + "sessionStop": { "enabled": true, "autoExtract": true, "threshold": 3 }, + "promptSubmit": { "enabled": false, "recordPrompts": false, "surfaceContext": true } + } +} ``` -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. - -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)) +--- -### Sync memories with remote +## How It Works -```bash -git mem sync # push + pull -git mem sync --push # push only -git mem sync --pull # pull only -``` +git-mem stores knowledge in two ways: -Pushes/pulls `refs/notes/mem` to/from origin. +### Git Notes (rich JSON) -### Generate MCP config +Memories are stored as JSON in git notes on `refs/notes/mem`. Each commit can have a note containing an array of memory entities: -```bash -git mem init-mcp +```text +refs/notes/mem + └── → { "memories": [{ id, content, type, confidence, tags, ... }] } ``` -Creates a `.mcp.json` in the current directory. Auto-detects global vs local install. - -Options: -- `--force` — Overwrite existing `.mcp.json` -- `--global` — Force use of globally installed binary - -## MCP Server Setup +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 -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). +### Git Trailers (lightweight metadata) -### Quick setup +When you `remember` on HEAD, git-mem also writes AI-* trailers directly into the commit message: -```bash -# If git-mem is installed globally: -git mem init-mcp +```text +AI-Decision: JWT over sessions — stateless API, scales horizontally +AI-Confidence: high +AI-Memory-Id: 3bf31da6-86a6-43cc-a1db-2f99da187107 +AI-Tags: auth, architecture ``` -This generates `.mcp.json`: - -```json -{ - "mcpServers": { - "git-mem": { - "command": "git-mem-mcp" - } - } -} -``` +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) -### Manual setup +--- -Add to your `.mcp.json` (or the equivalent config for your AI tool): - -```json -{ - "mcpServers": { - "git-mem": { - "command": "git-mem-mcp" - } - } -} -``` - -Or if using a local (non-global) install: - -```json -{ - "mcpServers": { - "git-mem": { - "command": "node", - "args": ["/path/to/git-mem/dist/mcp-server.js"] - } - } -} -``` +## Not using Claude? ### MCP Tools +The MCP server (`git-mem-mcp`) exposes git-mem to AI tools over stdio: + | Tool | Description | |------|-------------| -| `git_mem_remember` | Store a memory (decision, gotcha, convention, fact) attached to a commit | +| `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 currently staged changes | -| `git_mem_extract` | Scan commit history, score commits, and extract patterns as memories | +| `git_mem_context` | Find memories relevant to staged changes | +| `git_mem_extract` | Scan commit history and extract patterns as memories | -## How It Works -### Memory storage +--- -Memories are stored as JSON in git notes on `refs/notes/mem`. Each commit can have a note containing an array of memory entities: +## Prefer CLI Commands? -```text -refs/notes/mem - └── → { "memories": [ { id, content, type, confidence, tags, ... } ] } +### init + +```bash +git mem init +git mem init -y --commit-count 50 ``` -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: +- `-y, --yes` — Accept defaults without prompting +- `--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 -### How `remember` stores data +### remember -```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, ...}]} │ - └─────────────────────────┘ +Store a memory attached to the current commit. + +```bash +git mem remember "JWT chosen over sessions for stateless API" \ + --type decision \ + --tags "auth, architecture" \ + --confidence high ``` -### How `extract` captures knowledge from history +Writes to git notes and adds AI-* trailers to HEAD. -```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) │ - └─────────────────────────┘ -``` +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 +- `--no-trailers` — Skip writing AI-* trailers to the commit message -### How AI tools use git-mem via MCP +### recall -```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) │ -└───────────────────┘ +Search stored memories. + +```bash +git mem recall "authentication" +git mem recall --type decision --json ``` -## Environment Variables +Options: +- `-n, --limit ` — Max results (default: 10) +- `-t, --type ` — Filter by type +- `--since ` — Filter by date +- `--json` — Output as JSON -| 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/). | +### extract -Copy `.env.example` to `.env` and fill in values: +Scan commit history, score commits by interest, and extract decisions/gotchas/conventions as memories. ```bash -cp .env.example .env +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 ``` -If `--enrich` is used without an API key, git-mem prints a warning and falls back to heuristic extraction only. +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`) + +### context -## Development +Show memories relevant to staged changes. ```bash -git clone https://github.com/TonyCasey/git-mem.git -cd git-mem -npm install -npm run build +git add . +git mem context ``` -```bash -npm test # all tests -npm run test:unit # unit tests only -npm run test:integration # integration tests only +Options: +- `-n, --limit ` — Max results (default: 10) +- `--threshold ` — Min relevance score 0-1 (default: 0.1) +- `--json` — Output as JSON -# Run a single test: -node --import tsx --test tests/unit/application/services/MemoryService.test.ts -``` +### sync + +Push/pull memory refs to/from origin. ```bash -# Rebuild and reinstall globally (for manual testing): -./scripts/reinstall-global.sh +git mem sync # push + pull +git mem sync --push # push only +git mem sync --pull # pull only ``` + + +## Environment Variables + +| 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 3625addc0ed31e05ff7bd7ca85d1ab98227bfd40 Mon Sep 17 00:00:00 2001 From: Tony Casey Date: Fri, 13 Feb 2026 14:29:33 +0000 Subject: [PATCH 2/2] fix: reduce default `--commit-count` to 30 and update `.gitignore` for `.git-mem.json` --- .gitignore | 5 ++++- src/commands/init.ts | 6 +++--- 2 files changed, 7 insertions(+), 4 deletions(-) diff --git a/.gitignore b/.gitignore index 2215b45a..36a27c0f 100644 --- a/.gitignore +++ b/.gitignore @@ -97,4 +97,7 @@ dist/ # git-mem logs .git-mem/ -.dev/*/** \ No newline at end of file +.dev/*/** + +# git-mem +.git-mem.json diff --git a/src/commands/init.ts b/src/commands/init.ts index 4222d08f..b8a0dcb0 100644 --- a/src/commands/init.ts +++ b/src/commands/init.ts @@ -129,10 +129,10 @@ export async function initCommand(options: IInitCommandOptions, logger?: ILogger } // ── Prompts (skipped with --yes) ─────────────────────────────── - let commitCount = options.commitCount ? parseInt(options.commitCount, 10) : 100; + let commitCount = options.commitCount ? parseInt(options.commitCount, 10) : 30; if (!Number.isFinite(commitCount) || commitCount <= 0) { - console.log(`Invalid --commit-count value: "${options.commitCount}". Using default (100).`); - commitCount = 100; + console.log(`Invalid --commit-count value: "${options.commitCount}". Using default (30).`); + commitCount = 30; } let claudeIntegration = true;