diff --git a/README.md b/README.md
index f8958699..1188aecd 100644
--- a/README.md
+++ b/README.md
@@ -1,18 +1,23 @@
 # Git Mem
 
-Your git history is the perfect context for AI.
-It just needs to be extracted for agents....
+## Store AI knowledge IN each commit.
+
+### Extract from historical commits. 
 
 ## Why?
 
-Your git history already contains the decisions, conventions, and gotchas that matter — git-mem extracts them and makes them available to Claude automatically. 
+#### We should store information about the AI involvement in each commit.
+
+- What agent?
+- What model?
+- Knowledge for future agents.
 
 ## 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.
+#### Using built-in git features.. automatically.
 
-Every **new** commit is automatically populated with the folowing metadata..
+### Git Trailers
+Metadata key value pairs that exist inside a commit message (visible)
 
 - **AI-Agent:** Claude/Opus-4.5 
 - **AI-Decision:** JWT over sessions — stateless API, scales horizontally
@@ -20,7 +25,40 @@ Every **new** commit is automatically populated with the folowing metadata..
 - **AI-Confidence:** 0.95
 - **AI-Memory:** milestone/auth-implementation
 
-Going forward, AI knowledge will be embedded in each commit for future references
+### Git Notes 
+
+Metadata stored alongside commits in a separate refs/notes/mem. (hidden)
+
+The commit SHA never changes. Non-invasive. (used in retro-fitting existing commits)
+
+
+```aiignore
+# Note example
+
+{
+      "id": "3bf31da6-86a6-43cc-a1db-2f99da187107",
+      "content": "JWT over sessions — stateless API, scales horizontally" ,
+      "type": "decision",
+      "sha": "631671dbe0f7ef5e7bddec7849f232b3908ceb89",
+      "confidence": "high",
+      "source": "heuristic-extraction",
+      "lifecycle": "project",
+      "tags": [
+        "extraction",
+        "pattern:instead-of"
+      ],
+      "createdAt": "2026-02-12T23:35:46.153Z",
+      "updatedAt": "2026-02-12T23:35:46.153Z"
+    }
+```
+
+## Automatically?
+
+Yes, the last thing we want is another command to remember.
+
+If you use Claude Code cli, then git-mem uses the hooks behind the scenes to auto-popuplate the trailers & notes. There is nothing for you to do.
+
+If you use other AI cli tools, then you can use the mcp option.
 
 ---
 
@@ -32,10 +70,9 @@ cd your-repo
 git-mem init
 ```
 
-`init` sets up hooks, MCP config, .gitignore entries, and runs an initial extract from your history.
 
-See the [Getting Started Guide](./docs/getting-started.md) for full CLI and MCP setup docs.
 
+For more detailed information, see the [Getting Started Guide](./docs/getting-started.md)
 ## License
 
 MIT