docs: reposition messaging to lead with AI metadata (GIT-106)

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 <event>` 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 <event>` 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

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

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
 

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
-  └── <commit-sha> → { "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
+  └── <commit-sha> → { "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
 

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",