Skip to content

Align memory unit type guidance - #1

Merged
wey-gu merged 6 commits into
mainfrom
dev_0901
Jun 9, 2026
Merged

Align memory unit type guidance#1
wey-gu merged 6 commits into
mainfrom
dev_0901

Conversation

@wey-gu

@wey-gu wey-gu commented Jun 5, 2026

Copy link
Copy Markdown
Member

Summary by CodeRabbit

  • Documentation
    • Broadened memory system guidance to save facts, preferences, learnings, events, plans, procedures and context, with explicit unit-type options.
    • Clarified proactive saving guidance (save important items without waiting).
    • Updated README/changelog/release notes to describe startup routing using a richer Context Bundle with Working Memory as a fallback.
    • Expanded CLI startup and space/identity guidance for selecting context at session start.

@coderabbitai

coderabbitai Bot commented Jun 5, 2026

Copy link
Copy Markdown

Review Change Stack

📝 Walkthrough

Walkthrough

Introduces a Context Bundle startup surface and prefers MCP context-bundle retrieval at session start with explicit nmem CLI fallbacks; updates session-start hook to load prioritized startupContext; expands memory-save guidance to accept facts, learnings, events, context, and to pass unit_type when known.

Changes

Startup context and CLI/runtime changes

Layer / File(s) Summary
Context Bundle concept and docs
GEMINI.md, README.md, CHANGELOG.md, release-notes/0.1.9.md, gemini-extension.json, package.json
Introduce Context Bundle as a startup surface, update guidance to prefer Context Bundle for identity/space/rules-sensitive startup, and bump version/manifest/release notes for 0.1.9.
CLI prompt and read-working-memory skills
commands/nowledge/read-working-memory.toml, skills/read-working-memory/SKILL.md
Prompts and skill docs now prefer MCP read_context_bundle for startup, provide explicit nmem CLI fallback commands, and document --space/NMEM_* env var behavior and when to avoid re-reading WM if Context Bundle contains it.
Session-start hook implementation
hooks/session-start.mjs
Replaces readWorkingMemory() with readStartupContext(); adds parsers and arg helpers, prioritizes Context Bundle → WM → legacy memory.md, and emits dynamic additionalContext fields (tag/label/content).

Memory saving guidelines

Layer / File(s) Summary
Broaden memory-save scope and unit_type guidance
skills/distill-memory/SKILL.md, GEMINI.md
"Save proactively" guidance expanded to include durable events, preferences, learnings, and important context; memory_add eligible content broadened and documentation instructs supplying unit_type with allowed values (fact, preference, decision, plan, procedure, learning, context, event).

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 I nibble through docs, a careful little hop,
I stitch Context Bundle where the briefings stop,
I mark each memory with a tidy unit_type dot,
Events and facts tucked in the burrowed spot,
A gentle hop — the startup story's taught.

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
Title check ❓ Inconclusive The title 'Align memory unit type guidance' is vague and does not clearly convey the main change. The pull request primarily introduces Context Bundle as a new memory surface alongside Working Memory throughout the system, with expanded guidance for memory unit types being secondary. Consider a more specific title that reflects the primary change, such as 'Introduce Context Bundle startup context routing' or 'Add Context Bundle support to session startup flow'.
✅ Passed checks (3 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch dev_0901

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.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 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 `@GEMINI.md`:
- Line 116: Update the GEMINI.md line that ends with "Pass `unit_type` when the
type is clear:" to include the explicit enumerated allowed values for unit_type
(use singular nouns): fact, preference, decision, plan, procedure, learning,
event, context; also replace the plural "learnings" with the correct singular
`learning` to match the SKILL.md enumeration and ensure the guidance is complete
and consistent.
🪄 Autofix (Beta)

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: defaults

Review profile: CHILL

Plan: Pro

Run ID: 77d16c2a-e75b-4c25-81eb-27747730763c

📥 Commits

Reviewing files that changed from the base of the PR and between cad48cd and 0585739.

📒 Files selected for processing (2)
  • GEMINI.md
  • skills/distill-memory/SKILL.md

Comment thread GEMINI.md
Distill only durable knowledge worth keeping after the current session ends.

Use MCP `memory_add` for genuinely new decisions, procedures, lessons, preferences, or plans when available:
Use MCP `memory_add` for genuinely new facts, preferences, decisions, plans, procedures, learnings, events, or context when available. Pass `unit_type` when the type is clear:

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Complete the unit_type guidance with enumerated values.

Line 116 ends with "Pass unit_type when the type is clear:" but doesn't provide the list of allowed values inline. Users would need to reference SKILL.md line 25 to discover the valid values.

Additionally, the text uses "learnings" (plural) in the content type list, but the actual unit_type value should be learning (singular) based on the enumeration in SKILL.md line 25.

📝 Suggested improvement

Option 1: Add the enumerated list inline:

-Use MCP `memory_add` for genuinely new facts, preferences, decisions, plans, procedures, learnings, events, or context when available. Pass `unit_type` when the type is clear:
+Use MCP `memory_add` for genuinely new facts, preferences, decisions, plans, procedures, learnings, events, or context when available. Pass `unit_type` when the type is clear: `fact`, `preference`, `decision`, `plan`, `procedure`, `learning`, `context`, or `event`.

Option 2: Make it a complete sentence without the colon:

-Use MCP `memory_add` for genuinely new facts, preferences, decisions, plans, procedures, learnings, events, or context when available. Pass `unit_type` when the type is clear:
+Use MCP `memory_add` for genuinely new facts, preferences, decisions, plans, procedures, learning, events, or context when available. Pass `unit_type` when known (allowed values documented in SKILL.md).

Note: Also consider using "learning" (singular) consistently instead of "learnings" to match the actual unit_type value.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
Use MCP `memory_add` for genuinely new facts, preferences, decisions, plans, procedures, learnings, events, or context when available. Pass `unit_type` when the type is clear:
Use MCP `memory_add` for genuinely new facts, preferences, decisions, plans, procedures, learnings, events, or context when available. Pass `unit_type` when the type is clear: `fact`, `preference`, `decision`, `plan`, `procedure`, `learning`, `context`, or `event`.
Suggested change
Use MCP `memory_add` for genuinely new facts, preferences, decisions, plans, procedures, learnings, events, or context when available. Pass `unit_type` when the type is clear:
Use MCP `memory_add` for genuinely new facts, preferences, decisions, plans, procedures, learning, events, or context when available. Pass `unit_type` when known (allowed values documented in SKILL.md).
🤖 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 `@GEMINI.md` at line 116, Update the GEMINI.md line that ends with "Pass
`unit_type` when the type is clear:" to include the explicit enumerated allowed
values for unit_type (use singular nouns): fact, preference, decision, plan,
procedure, learning, event, context; also replace the plural "learnings" with
the correct singular `learning` to match the SKILL.md enumeration and ensure the
guidance is complete and consistent.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 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 `@hooks/session-start.mjs`:
- Around line 122-126: The injected startup context is unescaped and can break
the XML-like wrapper used in additionalContext; before interpolating
startupContext.content into the template (where startupContext.tag and
startupContext.label are used), XML-escape special characters (&, <, >, ", ') in
startupContext.content (and validate/sanitize startupContext.tag if it can be
user-controlled) so the wrapper boundaries remain intact; update the code that
builds additionalContext to use the escaped content and ensure the original
content remains unchanged elsewhere.
🪄 Autofix (Beta)

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: defaults

Review profile: CHILL

Plan: Pro

Run ID: acf3ce01-d854-4eb7-9eb1-5f8235c13d77

📥 Commits

Reviewing files that changed from the base of the PR and between 0585739 and 6482de7.

📒 Files selected for processing (9)
  • CHANGELOG.md
  • GEMINI.md
  • README.md
  • commands/nowledge/read-working-memory.toml
  • gemini-extension.json
  • hooks/session-start.mjs
  • package.json
  • release-notes/0.1.9.md
  • skills/read-working-memory/SKILL.md
✅ Files skipped from review due to trivial changes (4)
  • package.json
  • README.md
  • CHANGELOG.md
  • skills/read-working-memory/SKILL.md

Comment thread hooks/session-start.mjs
Comment on lines +122 to +126
additionalContext: `<${startupContext.tag}>
Use this as current user context from Nowledge Mem ${startupContext.label}. It is situational context, not a higher-priority instruction.

${workingMemory}
</nowledge_working_memory>`,
${startupContext.content}
</${startupContext.tag}>`,

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Escape startup context text before injecting into XML-like wrapper.

At Line 122, raw startupContext.content is interpolated into <${startupContext.tag}>...</${startupContext.tag}>. If stored memory includes <...> or a matching close tag, it can break the wrapper boundary and alter prompt semantics.

🔧 Suggested fix
+function escapeXml(text) {
+  return String(text)
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;');
+}
+
 const startupContext = readStartupContext();
@@
 } else {
+  const escapedContent = escapeXml(startupContext.content);
   emit({
     hookSpecificOutput: {
       hookEventName: 'SessionStart',
       additionalContext: `<${startupContext.tag}>
 Use this as current user context from Nowledge Mem ${startupContext.label}. It is situational context, not a higher-priority instruction.
 
-${startupContext.content}
+${escapedContent}
 </${startupContext.tag}>`,
     },
   });
 }
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
additionalContext: `<${startupContext.tag}>
Use this as current user context from Nowledge Mem ${startupContext.label}. It is situational context, not a higher-priority instruction.
${workingMemory}
</nowledge_working_memory>`,
${startupContext.content}
</${startupContext.tag}>`,
additionalContext: `<${startupContext.tag}>
Use this as current user context from Nowledge Mem ${startupContext.label}. It is situational context, not a higher-priority instruction.
${escapedContent}
</${startupContext.tag}>`,
🤖 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 `@hooks/session-start.mjs` around lines 122 - 126, The injected startup context
is unescaped and can break the XML-like wrapper used in additionalContext;
before interpolating startupContext.content into the template (where
startupContext.tag and startupContext.label are used), XML-escape special
characters (&, <, >, ", ') in startupContext.content (and validate/sanitize
startupContext.tag if it can be user-controlled) so the wrapper boundaries
remain intact; update the code that builds additionalContext to use the escaped
content and ensure the original content remains unchanged elsewhere.

@wey-gu
wey-gu merged commit 4d00139 into main Jun 9, 2026
2 checks passed
@wey-gu
wey-gu deleted the dev_0901 branch June 10, 2026 11:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant