diff --git a/CHANGELOG.md b/CHANGELOG.md index d6f2f9c9..b70d05dc 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..d8ba0ad1 100644 --- a/README.md +++ b/README.md @@ -1,28 +1,27 @@ -# 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. -## How? +git-mem adds AI metadata to every commit automatically — no workflow changes, no extra steps. -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. +## How? -Every **new** commit is automatically populated with the folowing metadata.. +Every commit gets AI trailers: -- **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 +```text +feat: add user authentication -Going forward, AI knowledge will be embedded in each commit for future references +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. ## Install @@ -32,9 +31,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..ecc8f562 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) | +```text +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",