Repository navigation
docs: surface unasked capture and the capture gap (0.1.15) - #25
Merged
Merged
Conversation
Both features shipped with only the Status section updated, which left the parts of the README people actually read describing the tool as it was two releases ago. The skill table still called /remember something you invoke. "What keeps it honest" listed staleness and never mentioned that staleness cannot detect an empty graph, which is the whole reason the capture gap exists. The Use section explained the two invocation forms and not the third. HOWTO, which is the file a beginner reads first, described capture as entirely manual — so the first unasked capture would have arrived with no explanation. Adds to HOWTO what a non-technical reader actually needs: that it will happen, that it is free, how to see what was captured, and that a note they did not want is a markdown file they can delete. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
📝 WalkthroughWalkthroughThe change documents automatic ChangesRemember documentation and release
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Actionable comments posted: 6
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@HOWTO.md`:
- Around line 177-179: Specify the language for both fenced output blocks by
changing the opening fences to text: update HOWTO.md lines 177-179 and README.md
lines 353-355. No other content changes are needed.
In `@package.json`:
- Line 3: Propagate version 0.1.15 across all release metadata: in package.json,
update both root version fields in package-lock.json from 0.1.4 to 0.1.15; in
.claude-plugin/plugin.json, update .claude-plugin/marketplace.json from 0.1.5 to
0.1.15.
In `@README.md`:
- Around line 81-88: The automatic-capture trigger descriptions omit conventions
and root causes. Update README.md lines 81-88 to include “a convention is
agreed” in the trigger list, and update HOWTO.md lines 173-175 to include both
root causes and conventions; preserve the existing automatic-capture behavior
and wording elsewhere.
- Around line 81-88: Update the README documentation for tree and doctor output
to distinguish uncaptured repositories from previously captured ones: use the
“nothing captured yet for <repo> — <commits> commits of history and an empty
graph” wording when no capture exists, and reserve the “commits since anything
was captured for <repo> — /remember is behind” wording for repositories with
prior captures.
- Line 353: Update the fenced code block at the README section around line 353
to include the text language identifier on its opening fence, resolving
markdownlint MD040 while leaving the block content unchanged.
- Around line 349-359: Revise the README section describing automatic capture to
present it as intended behavior rather than guaranteed invocation, since
skills/remember/SKILL.md does not enforce model calls. Remove or qualify the
claim that automatic capture is free, and state that request/tool-call billing
depends on the host platform rather than being guaranteed by this package.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: c20d1a0e-6b98-471e-8f0b-b70185251624
📒 Files selected for processing (4)
.claude-plugin/plugin.jsonHOWTO.mdREADME.mdpackage.json
Comment on lines
+177
to
+179
| ``` | ||
| captured 2 notes [decision, constraint] | ||
| ``` |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Add languages to both fenced output blocks.
markdownlint-cli2 reports MD040 for both blocks.
HOWTO.md#L177-L179: Change the opening fence to```text.README.md#L353-L355: Change the opening fence to```text.
🧰 Tools
🪛 markdownlint-cli2 (0.23.2)
[warning] 177-177: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
📍 Affects 2 files
HOWTO.md#L177-L179(this comment)README.md#L353-L355
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@HOWTO.md` around lines 177 - 179, Specify the language for both fenced output
blocks by changing the opening fences to text: update HOWTO.md lines 177-179 and
README.md lines 353-355. No other content changes are needed.
Source: Linters/SAST tools
| { | ||
| "name": "@vib795/agent-memory", | ||
| "version": "0.1.14", | ||
| "version": "0.1.15", |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Propagate version 0.1.15 to all release metadata.
The changed manifests use 0.1.15, but related metadata still uses older versions.
package.json#L3-L3: update both root version fields inpackage-lock.jsonfrom0.1.4to0.1.15..claude-plugin/plugin.json#L4-L4: update.claude-plugin/marketplace.jsonfrom0.1.5to0.1.15.
📍 Affects 2 files
package.json#L3-L3(this comment).claude-plugin/plugin.json#L4-L4
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@package.json` at line 3, Propagate version 0.1.15 across all release
metadata: in package.json, update both root version fields in package-lock.json
from 0.1.4 to 0.1.15; in .claude-plugin/plugin.json, update
.claude-plugin/marketplace.json from 0.1.5 to 0.1.15.
Comment on lines
+81
to
+88
| - **An empty graph says so.** Staleness cannot tell you a repo has nothing in it — | ||
| a repo nobody captured in has no stale notes either, so it reads as fully covered. | ||
| `tree` and `doctor` print `47 commits since anything was captured here` instead. | ||
| Silence has to mean covered, never empty. | ||
| - **Capture does not wait to be asked.** The agent invokes `/remember` itself when a | ||
| decision settles, a constraint surfaces or a root cause is found, and says so in one | ||
| line. Judged by the model in the turn where the context still exists — never on a | ||
| timer or a tool count, because volume is what makes a graph useless. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Align the automatic-capture trigger lists.
Both sections omit conventions, although the executable skill and README.md Lines 349-351 document them.
README.md#L81-L88: Add “a convention is agreed” to the trigger list.HOWTO.md#L173-L175: Add root causes and conventions to the automatic-capture description.
📍 Affects 2 files
README.md#L81-L88(this comment)HOWTO.md#L173-L175
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@README.md` around lines 81 - 88, The automatic-capture trigger descriptions
omit conventions and root causes. Update README.md lines 81-88 to include “a
convention is agreed” in the trigger list, and update HOWTO.md lines 173-175 to
include both root causes and conventions; preserve the existing
automatic-capture behavior and wording elsewhere.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
rg -n -C 8 \
'buildDigest|captureGapCommits|doctor|tree|anything was captured|/remember' \
--glob '*.js' \
--glob '*.ts' \
--glob '*.json' \
--glob '*.md' \
. || trueRepository: vib795/agent-memory
Length of output: 50377
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '%s\n' '--- CLI symbols ---'
rg -n -C 12 \
'case .tree.|case .doctor.|buildTree|renderTree|captureGap|captureGapCommits|doctor' \
src/cli.js src/*.js test tests 2>/dev/null || true
printf '%s\n' '--- relevant source ranges ---'
for f in src/cli.js src/digest.js src/staleness.js; do
if [ -f "$f" ]; then
printf '\n--- %s ---\n' "$f"
sed -n '1,280p' "$f"
fi
done
printf '%s\n' '--- tests mentioning capture gaps and command output ---'
rg -n -C 10 \
'capture gap|captureGap|anything was captured|empty graph|agent-memory tree|agent-memory doctor|doctor' \
test tests 2>/dev/null || trueRepository: vib795/agent-memory
Length of output: 50375
Correct the documented tree and doctor output.
For an uncaptured repository, both commands print nothing captured yet for <repo> — <commits> commits of history and an empty graph. They print the commits since anything was captured for <repo> — /remember is behind form only when a prior capture exists.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@README.md` around lines 81 - 88, Update the README documentation for tree and
doctor output to distinguish uncaptured repositories from previously captured
ones: use the “nothing captured yet for <repo> — <commits> commits of history
and an empty graph” wording when no capture exists, and reserve the “commits
since anything was captured for <repo> — /remember is behind” wording for
repositories with prior captures.
Comment on lines
+349
to
+359
| You will also see it fire without being asked, when a decision settles, a constraint | ||
| surfaces, a root cause is found or a convention is agreed. It reports one line at the | ||
| end of whatever it was already answering and carries on: | ||
|
|
||
| ``` | ||
| captured 2 notes [decision, constraint] | ||
| ``` | ||
|
|
||
| That costs nothing — a request is charged per prompt, not per tool call, so capture | ||
| inside a turn you already paid for is free. Only typing `/remember` yourself spends | ||
| one. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
rg -n -C 8 -i \
'automatic|auto.?capture|remember|capture|prompt|tool call|charge|billing' \
--glob '*.js' \
--glob '*.ts' \
--glob '*.json' \
--glob '*.md' \
. || trueRepository: vib795/agent-memory
Length of output: 50378
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '%s\n' '--- candidate skill and test files ---'
git ls-files | rg '(^|/)(skills|test|src)/|package.json$|README.md$|HOWTO.md$' | head -200
printf '%s\n' '--- automatic-capture and billing references outside README.md ---'
rg -n -i \
'automatic|auto.?capture|without being asked|captured [0-9]+ notes|same request|no extra|extra cost|charged per|per prompt|per message|tool call|tool count' \
--glob '!README.md' --glob '!package-lock.json' \
skills test src HOWTO.md package.json 2>/dev/null | head -240
printf '%s\n' '--- skill outlines ---'
for f in $(git ls-files 'skills/*/SKILL.md'); do
echo "### $f"
wc -l "$f"
ast-grep outline "$f" 2>/dev/null | head -80 || true
doneRepository: vib795/agent-memory
Length of output: 2408
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '%s\n' '--- skills/remember/SKILL.md ---'
cat -n skills/remember/SKILL.md | sed -n '1,90p'
printf '%s\n' '--- skills/handoff/SKILL.md capture instructions ---'
rg -n -C 12 -i \
'remember|capture|free|charged|request|prompt|tool|automatic' \
skills/handoff/SKILL.md
printf '%s\n' '--- source billing and capture-report code ---'
cat -n src/digest.js | sed -n '1,90p'
cat -n src/cli.js | sed -n '1,180p'
printf '%s\n' '--- tests mentioning skills, capture, or billing ---'
rg -n -C 8 -i \
'remember|capture|captured|billing|charged|free|request|prompt|tool' \
test skills package.json HOWTO.md | head -300Repository: vib795/agent-memory
Length of output: 37896
Qualify the automatic-capture and billing claims.
skills/remember/SKILL.md instructs the agent to capture unasked, but no code or test enforces model invocation. The package also cannot guarantee host-platform billing semantics. Qualify or remove the statement that automatic capture adds no request charge.
🧰 Tools
🪛 markdownlint-cli2 (0.23.2)
[warning] 353-353: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@README.md` around lines 349 - 359, Revise the README section describing
automatic capture to present it as intended behavior rather than guaranteed
invocation, since skills/remember/SKILL.md does not enforce model calls. Remove
or qualify the claim that automatic capture is free, and state that
request/tool-call billing depends on the host platform rather than being
guaranteed by this package.
| surfaces, a root cause is found or a convention is agreed. It reports one line at the | ||
| end of whatever it was already answering and carries on: | ||
|
|
||
| ``` |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Add a language identifier to the output fence.
markdownlint-cli2 reports MD040 for the fence at Line 353. Add text to the opening fence so the README passes the configured Markdown lint.
🧰 Tools
🪛 markdownlint-cli2 (0.23.2)
[warning] 353-353: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@README.md` at line 353, Update the fenced code block at the README section
around line 353 to include the text language identifier on its opening fence,
resolving markdownlint MD040 while leaving the block content unchanged.
Source: Linters/SAST tools
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
0.1.13 and 0.1.14 each updated only the Status section, which left the parts of the README people actually read describing the tool as it was two releases ago.
/remember— "Captures durable knowledge into a cross-repo graph" (something you invoke)That last one mattered most: HOWTO is what a beginner reads first, so the first unasked capture would have arrived with no explanation at all.
Changes
/remembernow says it fires on its own when a juncture passes./recall,agent-memory tree), and that a note they did not want is a markdown file they can delete.Verification
grepconfirms no section still claims capture is explicit or that nothing fires on its own.🤖 Generated with Claude Code
Summary by CodeRabbit
Documentation
/remembercapture for settled decisions and constraints.treeanddoctor.Chores