From cd78872cbe05914606057dfd138165cafc76d735 Mon Sep 17 00:00:00 2001 From: Tony Casey Date: Sun, 15 Feb 2026 18:40:38 +0000 Subject: [PATCH 1/2] docs: reposition messaging to lead with AI metadata (GIT-106) - README: lead with "Track AI contributions in your git history" - getting-started: show AI trailers first, Claude Code hooks as extra feature - Update config references from .git-mem.json to .git-mem/.git-mem.yaml - CHANGELOG: consolidate post-0.3.0 work into 0.4.0 release - Bump version to 0.4.0 Co-Authored-By: Claude Opus 4.5 AI-Agent: Claude-Code/2.1.42 AI-Model: claude-opus-4-5-20251101 AI-Decision: The project has repositioned its messaging to lead with AI metadata tracking rather than memory extraction, suggesting the primary value prop is tracking AI contributions in git history. AI-Confidence: verified AI-Tags: documentation, product-positioning, ai-metadata, configuration, yaml, migration, breaking-change, versioning, changelog, feature-consolidation, hooks, error-handling, config, reliability, git-trailers, commit-format, timeout, claude-code AI-Lifecycle: project AI-Memory-Id: 56f52b0b AI-Source: llm-enrichment --- CHANGELOG.md | 60 +++++++++++--------- CLAUDE.md | 12 +++- README.md | 46 ++++++++++------ docs/getting-started.md | 118 +++++++++++++++++++++------------------- package.json | 2 +- 5 files changed, 139 insertions(+), 99 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d6f2f9c9..96b4764b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,13 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Changed + +- **Documentation repositioning** — README and getting-started now lead with AI metadata tracking, memory as "level up" + +## [0.4.0] - 2026-02-15 + ### Added -- **Smart commit analysis** — commit-msg hook that automatically analyzes commit messages and adds AI-* trailers: - - Detects memory type (decision, gotcha, convention, fact) from heuristic patterns - - Infers tags from conventional commit scope and staged file paths +- **Intent extraction** — PromptSubmitHandler extracts keywords from prompts to surface relevant memories: + - `IIntentExtractor` interface and `IntentExtractor` service + - `loadWithQuery` method on `MemoryContextLoader` for targeted recall + - Configurable via `promptSubmit.extractIntent` in config +- **Commit message bodies** — memory context now includes full commit message bodies, not just subjects +- **YAML configuration** — `.git-mem.yaml` replaces `.git-mem.json`: + - Config now lives in `.git-mem/` directory + - Cleaner, more readable format + - Backwards compatible migration from JSON +- **LLM enrichment in hooks** — commit-msg hook can use LLM to enhance memory extraction: + - Loads `.env` for `ANTHROPIC_API_KEY` + - Configurable timeout (default 8s) +- **Smart commit analysis** — commit-msg hook automatically analyzes commits and adds AI trailers: + - Detects memory type (decision, gotcha, convention, fact) from patterns + - Infers tags from conventional commit scope and file paths - Adds AI-Agent, AI-Model, AI-Confidence, AI-Lifecycle, AI-Memory-Id trailers - - Configurable via `.git-mem.json` (autoAnalyze, inferTags, requireType, defaultLifecycle) + +### Fixed + +- Edge cases in commit-msg hook (empty messages, missing env vars) +- Duplicate Agent/Model trailers prevention +- Hook chaining — all hooks now install by default ## [0.3.0] - 2026-02-12 @@ -23,28 +46,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - `session-start` — loads stored memories into Claude's context at session start - `session-stop` — captures new memories from commits made during the session - `prompt-submit` — surfaces relevant memories per prompt (disabled by default) -- **`git-mem init-hooks`** command — one-command setup for Claude Code hooks: - - Creates `.claude/settings.json` with hook registrations - - Creates `.git-mem.json` with default configuration - - Safe merge preserves other tools' hooks in `settings.json` - - `--remove` flag cleanly uninstalls git-mem hooks only - - `--scope user` for `~/.claude/settings.json` (user-wide) -- **Unified `git-mem hook ` command** — single entry point for all hook events, reads JSON from stdin, routes to handlers via EventBus -- **DI container** (awilix) — replaces manual service instantiation across CLI, MCP, and hooks with centralized dependency injection -- **EventBus** — pub/sub event dispatch with error isolation; failing handlers don't block other handlers or crash the hook -- **`.git-mem.json` configuration** — per-project hook settings (enable/disable events, memory limits, auto-liberate threshold) -- **Hook handlers:** - - `SessionStartHandler` — loads and formats memories as markdown context - - `SessionStopHandler` — delegates to `SessionCaptureService` for 24h rolling commit scan - - `PromptSubmitHandler` — loads relevant memories for prompt context -- **Hook services:** - - `MemoryContextLoader` — loads memories with configurable limits - - `ContextFormatter` — formats memories as structured markdown - - `SessionCaptureService` — scans recent commits via `LiberateService`, extracts memories +- **`git-mem init-hooks`** command — one-command setup for Claude Code hooks +- **Unified `git-mem hook ` command** — single entry point for all hook events +- **DI container** (awilix) — centralized dependency injection +- **EventBus** — pub/sub event dispatch with error isolation +- **`.git-mem.json` configuration** — per-project hook settings ### Changed -- CLI commands now resolve services from DI container instead of manual instantiation +- CLI commands now resolve services from DI container - MCP tools now resolve services from DI container ## [0.2.1] - 2026-02-10 @@ -57,7 +67,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added -- MCP server (`git-mem-mcp`) with 4 tools: remember, recall, context, liberate +- MCP server (`git-mem-mcp`) with 4 tools: remember, recall, context, extract - `git-mem init-mcp` command for MCP server configuration - `git-mem sync` command for syncing memories across remotes @@ -69,7 +79,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - `git-mem remember` — store memories as git notes - `git-mem recall` — search and retrieve memories - `git-mem context` — match staged changes against stored memories -- `git-mem liberate` — scan git history, score commits, extract memories +- `git-mem extract` — scan git history, score commits, extract memories - Clean architecture (Domain → Application → Infrastructure) - Git notes storage on `refs/notes/mem` - Heuristic pattern extraction from conventional commits diff --git a/CLAUDE.md b/CLAUDE.md index 82652243..da13e8a7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -75,7 +75,7 @@ Uses **`node:test`** (native Node.js test runner) with **`tsx`** for TypeScript, - **`cwd` parameter**: Must be threaded through all service calls when operating on a repo that isn't the current working directory - **Commit triage**: Weighted scoring based on conventional prefixes, decision keywords, diff size, PR merges - **TypeScript config**: Relaxed strict mode for development (`strict: false` in tsconfig.json) -- **Hook config**: `.git-mem.json` at project root, loaded by `src/hooks/utils/config.ts`. Never throws — returns defaults on error +- **Hook config**: `.git-mem/.git-mem.yaml` loaded by `src/hooks/utils/config.ts`. Never throws — returns defaults on error - **Hook stdin**: `src/hooks/utils/stdin.ts` reads JSON from stdin. Returns `{}` on TTY or parse error — hooks must never crash - **EventBus error isolation**: Handler exceptions are caught and returned as failed `IEventResult[]` — one failing handler doesn't block others - **Hook timeout**: 10s hard limit via `setupShutdown()` — hooks must never hang Claude Code @@ -91,6 +91,8 @@ Rules are automatically loaded as context. See `.claude/rules/`: - `code-quality-rules.md` - TypeScript/ESLint configuration, error prevention - `git-rules.md` - Commit workflow, PR creation, memory milestones - `testing-principles.md` - Testing pyramid, mocking strategies +- `memory-rules.md` - Handling session memory + ### TypeScript Rules - `coding-standards.md` - Naming conventions, type safety, async patterns @@ -101,5 +103,13 @@ Rules are automatically loaded as context. See `.claude/rules/`: ## Git Workflow - Branch per Linear issue, named with ticket number (e.g. `GIT-15`) +- Use the SKILL .claude/skills/github/SKILL.md for interacting with GitHub +- PR workflow use the skill .claude/skills/pr/SKILL.md + - Create the PR + - Wait for 120 seconds to allow for review from coderabbit + - Address comments directly inline to the comment + - if a fix is applied, mark the comment as resolved + - wait for another 120 seconds to allow for review from coderabbit + - repeat the steps until all comments are resolved - PRs merge into `main` - Clean up feature branches after merge diff --git a/README.md b/README.md index 39d3ed6f..7c44f3fa 100644 --- a/README.md +++ b/README.md @@ -1,28 +1,28 @@ -# Git Mem +# git-mem -Your git history is the perfect context for AI. -It just needs to be extracted for agents.... +Track AI contributions in your git history. ## Why? -Your git history already contains the decisions, conventions, and gotchas that matter — git-mem extracts them and makes them available to Claude automatically. +AI writes code now. Your commits should show when, which agent, and which model. + +git-mem adds AI metadata to every commit automatically — no workflow changes, no extra steps. ## How? -When initialized in your repo, git-mem reviews your last (n) commits and extracts knowledge automatically. -Each commit is updated with background AI metadata, which Claude can use to improve its understanding of your codebase. +Every commit gets AI trailers: -Every **new** commit is automatically populated with the folowing metadata.. +``` +feat: add user authentication -- **AI-Agent:** Claude/Opus-4.5 -- **AI-Decision:** JWT over sessions — stateless API, scales horizontally -- **AI-Context:** [pattern/middleware, entity/auth-module] -- **AI-Confidence:** 0.95 -- **AI-Memory:** milestone/auth-implementation +AI-Agent: claude-code +AI-Model: claude-sonnet-4-5-20250929 +AI-Decision: JWT over sessions — stateless API, scales horizontally +AI-Context: [pattern/middleware, entity/auth-module] -Going forward, AI knowledge will be embedded in each commit for future references +``` ---- +That's it. Your git history now tracks AI contributions. ## Install @@ -32,9 +32,23 @@ cd your-repo git-mem init ``` -`init` sets up hooks, MCP config, .gitignore entries, and runs an initial extract from your history. +30 seconds. Done. + +## What else? + +git-mem also extracts decisions, conventions, and gotchas from your commit history — and makes them available to your AI agent as persistent memory. + +Your agent stops re-learning your codebase every session. + +```bash +# Extract knowledge from recent commits +git-mem extract + +# Query what git-mem knows +git-mem recall "authentication" +``` -See the [Getting Started Guide](./docs/getting-started.md) for full CLI and MCP setup docs. +See the [Getting Started Guide](./docs/getting-started.md) for CLI and MCP setup. ## License diff --git a/docs/getting-started.md b/docs/getting-started.md index dfd72e67..b8a8b40a 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -2,10 +2,6 @@ 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) - ## Quick Start ```bash @@ -14,57 +10,35 @@ cd your-repo git-mem init ``` -`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) - ---- - -## Using Claude? +That's it. Every commit now includes AI metadata: -All of the processes happen automatically through Claude's hook events. - -| 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) | +``` +feat: add user authentication -Settings are stored in `.git-mem.json`: - -```json -{ - "hooks": { - "enabled": true, - "sessionStart": { "enabled": true, "memoryLimit": 20 }, - "sessionStop": { "enabled": true, "autoExtract": true, "threshold": 3 }, - "promptSubmit": { "enabled": false, "recordPrompts": false, "surfaceContext": true } - } -} +AI-Agent: claude-code +AI-Model: claude-sonnet-4-5-20250929 +AI-Decision: JWT over sessions — stateless API, scales horizontally +AI-Context: [pattern/middleware, entity/auth-module] ``` --- -## How It Works +## What `init` sets up -git-mem stores knowledge in two ways: +1. **Git hooks** — `prepare-commit-msg` and `commit-msg` add AI trailers to every commit +2. **Config** — `.git-mem/.git-mem.yaml` with settings +3. **MCP server** — `.mcp.json` for AI tool integration +4. **Gitignore** — keeps local config out of version control -### Git Notes (rich JSON) +Two bin commands are available after installation: +- `git-mem` (also works as `git mem` — git subcommand) +- `git-mem-mcp` (MCP server for AI tools) -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, ... }] } -``` +## How It Works -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 +git-mem stores knowledge in two ways: ### Git Trailers (lightweight metadata) @@ -82,21 +56,20 @@ Trailers are: - **Visible** — show up in `git log`, GitHub, and code review tools - **Only on new commits** — `extract` writes notes only (no history rewrite) ---- - -## Not using Claude? -### MCP Tools +### Git Notes (rich JSON) -The MCP server (`git-mem-mcp`) exposes git-mem to AI tools over stdio: +Memories are stored as JSON in git notes on `refs/notes/mem`. Each commit can have a note containing an array of memory entities: -| 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 | +```text +refs/notes/mem + └── → { "memories": [{ id, content, type, confidence, tags, ... }] } +``` +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 --- @@ -152,7 +125,7 @@ Options: ### extract -Scan commit history, score commits by interest, and extract decisions/gotchas/conventions as memories. +Scans commit history, scores commits by interest, and extract decisions/gotchas/conventions as memories for AI context. ```bash git mem extract --since 2024-01-01 --dry-run @@ -191,6 +164,39 @@ git mem sync --push # push only git mem sync --pull # pull only ``` +--- + +## Using Claude Code? + +If you use Claude Code, git-mem can do more than just add trailers & notes — it can give Claude persistent memory across sessions. + +`init` also sets up Claude Code hooks in `.claude/settings.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) | + +These hooks read the AI trailers from your commits and build a searchable memory layer that Claude can query. + +Settings are in `.git-mem/.git-mem.yaml`: + +```yaml +hooks: + enabled: true + sessionStart: + enabled: true + memoryLimit: 20 + sessionStop: + enabled: true + autoExtract: true + threshold: 3 + promptSubmit: + enabled: false + surfaceContext: true +``` + ## Environment Variables diff --git a/package.json b/package.json index 516d23eb..f6f51931 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "git-mem", - "version": "0.3.0", + "version": "0.4.0", "description": "Git-native memory layer for AI coding tools. Store decisions, context, and knowledge directly in your git repository using commit trailers and git notes.", "bin": { "git-mem": "dist/cli.js", From c8ecfdfc7f3657c8bea37a1982dc0b6700dbd4fb Mon Sep 17 00:00:00 2001 From: Tony Casey Date: Sun, 15 Feb 2026 18:45:02 +0000 Subject: [PATCH 2/2] fix: address CodeRabbit review comments (GIT-106) - Hyphenate "Backwards-compatible" in CHANGELOG - Add language identifiers to code blocks in README and getting-started Co-Authored-By: Claude Opus 4.5 AI-Agent: Claude-Code/2.1.42 AI-Model: claude-opus-4-5-20251101 AI-Convention: Documentation code blocks should include language identifiers for proper syntax highlighting and formatting. AI-Confidence: verified AI-Tags: documentation, markdown, code-blocks, syntax-highlighting, grammar, changelog, technical-writing, code-review, tooling, development-process AI-Lifecycle: project AI-Memory-Id: 5034f6a6 AI-Source: llm-enrichment --- CHANGELOG.md | 2 +- README.md | 3 +-- docs/getting-started.md | 2 +- 3 files changed, 3 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 96b4764b..b70d05dc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -23,7 +23,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - **YAML configuration** — `.git-mem.yaml` replaces `.git-mem.json`: - Config now lives in `.git-mem/` directory - Cleaner, more readable format - - Backwards compatible migration from JSON + - Backwards-compatible migration from JSON - **LLM enrichment in hooks** — commit-msg hook can use LLM to enhance memory extraction: - Loads `.env` for `ANTHROPIC_API_KEY` - Configurable timeout (default 8s) diff --git a/README.md b/README.md index 7c44f3fa..d8ba0ad1 100644 --- a/README.md +++ b/README.md @@ -12,14 +12,13 @@ git-mem adds AI metadata to every commit automatically — no workflow changes, Every commit gets AI trailers: -``` +```text feat: add user authentication AI-Agent: claude-code AI-Model: claude-sonnet-4-5-20250929 AI-Decision: JWT over sessions — stateless API, scales horizontally AI-Context: [pattern/middleware, entity/auth-module] - ``` That's it. Your git history now tracks AI contributions. diff --git a/docs/getting-started.md b/docs/getting-started.md index b8a8b40a..ecc8f562 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -12,7 +12,7 @@ git-mem init That's it. Every commit now includes AI metadata: -``` +```text feat: add user authentication AI-Agent: claude-code