@vib795/agent-memory 0.1.11 → 0.1.13

package/README.md

@@ -322,32 +322,111 @@ A transcript summary reads fine and still leaves the next agent asking questions
 
 ## Use
 
-Two different jobs, and it is worth being clear about which is which.
+Three commands, two different jobs. You type the slash command in your agent; the
+agent runs the CLI. The terminal equivalents are shown so you can see what it did,
+and drive it by hand when you want to.
 
-**Moving a thread between windows.** In window A:
+### `/remember` — keep what stays true
+
+Mid-session, when something worth keeping has been established:
 
 ```
-/handoff
+/remember
+/remember the retry policy on the orders webhook
 ```
 
-It prints a pickup line. In window B, any repo, paste it:
+Bare, it selects the durable knowledge itself. With an argument, it writes that and
+nothing else. Either way it makes one terminal call, and `write` reports each id:
 
 ```
-Read C:\Users\you\.agents\handoffs\migrate-orders-to-result-type.md and continue this work. Follow the Next action.
+created auth-service [system]
+created use-sessions [decision]
+warning: use-sessions: redacted 1x github-token
+```
+
+That warning is the redactor firing before anything reached disk. The skill then
+repeats the list back to you with titles attached, so you can see what was captured
+without opening the files.
+
+What it ran, which you can run yourself:
+
+```bash
+agent-memory write --from-json - --source remember <<'JSON'
+{"nodes":[
+  {"id":"use-sessions","type":"decision",
+   "title":"Chose server sessions over JWT",
+   "body":"Why: revocation had to take effect immediately.\nRejected: short-TTL JWT, because logout would lag by the TTL.\nImplemented in src/auth/session.js:42.",
+   "edges":[{"rel":"evidence-for","dst":"auth-service"}]}
+]}
+JSON
 ```
 
-**Keeping what stays true.** `/handoff` also writes durable knowledge into the graph
-in the same request — same turn, no extra credit. Mid-session, when something worth
-keeping is established and you are not switching windows:
+### `/recall` — answer from memory before deriving again
+
+You rarely type this one. Ask a question memory should already answer and the agent
+invokes it on its own, because the skill description advertises what is in the store:
 
 ```
-/remember
-/remember the retry policy on the orders webhook
+Why do we use sessions instead of JWT here?
+/recall the auth decision
 ```
 
-And in any repo, later, ask a question that memory should already answer. The agent
-invokes `/recall` on its own, because the skill description tells it what is in
-there.
+It reads the routing map first, then pulls only the notes it needs:
+
+```bash
+agent-memory tree                      # what exists, scoped to this repo
+agent-memory get use-sessions --depth 1   # that note plus its neighbourhood
+agent-memory search "session revocation"  # full text, when the tree misses
+```
+
+A note that is still current prints clean, with its edges:
+
+```
+## use-sessions  [decision]  depth 0
+Chose server sessions over JWT
+
+Why: revocation had to take effect immediately.
+
+  -> evidence-for auth-service
+```
+
+Once the code has moved on underneath it, the same note arrives carrying the warning.
+This is the part that keeps the store honest:
+
+```
+## use-sessions  [decision]  depth 0  [captured 47 commits ago — verify before trusting]
+```
+
+### `/handoff` — move a thread to another window
+
+In window A:
+
+```
+/handoff
+```
+
+It writes the working-state file and prints a pickup line. In window B, any repo,
+paste it:
+
+```
+Read ~/.agents/handoffs/migrate-orders-to-result-type.md and continue this work. Follow the Next action.
+```
+
+`/handoff` also writes durable knowledge into the graph in the same request — same
+turn, no extra request charged. To see what it produced:
+
+```bash
+ls ~/.agents/handoffs/           # index.md, <thread>.md, one <thread>.prev.md
+agent-memory tree                # the nodes it captured on the way past
+```
+
+### Housekeeping
+
+```bash
+agent-memory doctor              # after install, after an upgrade, when something looks off
+agent-memory compact             # dedup, decay, regenerate the routing digest
+agent-memory tree --repo         # every repo, not just this one
+```
 
 ## Where things live
 
@@ -386,11 +465,27 @@ that drifts as the work progresses does not create a duplicate.
 
 ## Status
 
-Capture is **explicit**. You invoke it, or `/handoff` does; nothing fires on its own.
+Capture is **judged, not scheduled.** You invoke it, `/handoff` does, or the agent
+does on its own when a juncture has just passed — a decision settled, a constraint
+found, a root cause identified, a convention agreed. It says so in one line and
+carries on with what you actually asked:
+
+```
+captured 2 notes [decision, constraint]
+```
+
+Nothing fires on a timer, on a tool count, or on every reply. That distinction is the
+whole design: a store full of task chatter is worse than an empty one, because it
+buries the four notes that mattered. The judgment of what is durable belongs to the
+model, in the turn where the context still exists; there is no keyword list deciding
+it. And because a request is charged per prompt rather than per tool call, capture
+that rides inside a turn you already paid for is free — which is why it can afford to
+happen at the moment the knowledge is fresh instead of whenever someone remembers.
 
 Not built yet, by choice:
 
-- Automatic or ambient capture
+- A capture-gap signal — the store knows when a note has gone stale, but not yet when
+  a repo has moved a hundred commits with nothing captured at all
 - Team sharing, multi-machine sync
 - An MCP server. It would read this same store, so it is an addition, not a rewrite.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vib795/agent-memory",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "Durable cross-repo knowledge graph for GitHub Copilot and Claude Code. Markdown source of truth, disposable SQLite index, zero runtime dependencies.",
   "keywords": [
     "github-copilot",

package/skills/remember/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: remember
 version: 0.1.0
-description: Capture durable project knowledge from the current conversation into the shared memory graph, so a later conversation in any window or repository already knows it. Use when the user says remember this, save this, note this for later, or /remember.
+description: Capture durable project knowledge from this conversation into a cross-repo memory graph, so a later conversation anywhere already knows it. Use when the user says remember this, save this, note this for later, or /remember. Also invoke it unasked when a juncture passes - a decision settled, a constraint found, a root cause identified, a convention agreed - then say so in one line and carry on.
 license: MIT
 allowed-tools: Bash Read Write
 triggers:
@@ -25,11 +25,51 @@ call. Do not ask the user to confirm each node.
 
 ---
 
-## Two forms
+## Three forms
 
 - **`/remember`** — you select the durable knowledge from the conversation so far.
 - **`/remember <what>`** — the user named the thing. Write that, with full context
   from the conversation, and write nothing unrelated to it.
+- **Unasked** — you noticed a juncture pass and captured it without being told.
+
+### Capturing unasked
+
+A memory that only grows when someone remembers to grow it stays thin, and thin is
+how it dies: the one fact worth having is the one nobody stopped to write down.
+
+Invoke this yourself the moment one of these has just happened, in the same turn:
+
+- a **decision** was settled, and the reasons and rejected options are still in view
+- a **constraint** surfaced — a blocked tool, a policy, an environment restriction
+- a **root cause** was found, as opposed to a symptom worked around
+- a **convention** was agreed, or discovered by reading the code
+
+Do not capture on a timer, on a tool count, or at every reply. Those produce volume,
+and volume is what makes a graph useless — a store full of task chatter is worse than
+an empty one, because it buries the four notes that mattered.
+
+Never capture: task status, what you are about to do next, anything already in the
+graph, or anything that will be false next month. If you captured a juncture earlier
+in this conversation, do not capture it again because it came up a second time.
+
+**It is free, and that is the point.** A request is charged per prompt, not per tool
+call, so capturing inside a turn you were already answering costs nothing. Only a
+user typing `/remember` spends a request. That is the whole reason to do this
+yourself rather than wait to be asked.
+
+**Report it in one line, then carry on:**
+
+```
+captured 2 notes [decision, constraint]
+```
+
+At the end of the answer you were already giving. Do not print the JSON, do not
+summarize what you wrote, and do not make it the subject of the reply — the user
+asked you about something else and is still waiting for it. One line is enough for
+them to know it happened and to run `/recall` if they want the detail.
+
+If nothing durable happened, say nothing at all. Silence is the correct output for
+most turns.
 
 ---