brain-memory 0.1.0-beta.32 → 0.1.0-beta.33

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -6,6 +6,47 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
6
6
 
7
7
  ## [Unreleased]
8
8
 
9
+ ## [0.1.0-beta.33] - 2026-07-04
10
+
11
+ _Covers everything since v0.1.0-beta.31, including the changes first shipped in the changelog-less 0.1.0-beta.32._
12
+
13
+ ### Added
14
+
15
+ - **Recall receipts — memory that visibly fires.** Every memory returned by
16
+ `brain recall` and `brain session-start` now carries an engine-minted
17
+ `receipt` line (`◉ memory: "<title>" (<type>, <age>)`). Hosts end a response
18
+ with the receipts of the memories that actually shaped it — max 3, copied
19
+ verbatim, pinned facts only when decisive, none when none were used. A
20
+ receipt can only exist if the engine returned that memory, so receipts
21
+ cannot be hallucinated.
22
+ - **Four new agent hosts.** Native integrations under `integrations/` for
23
+ **OpenClaw / NVIDIA NemoClaw** (memory-slot plugin `openclaw-brain-memory`
24
+ replacing `memory-core`, slot-neutral hook pack, ClawHub skill, NemoClaw
25
+ egress-policy preset — all live-verified), **Hermes Agent** (full
26
+ `MemoryProvider` plugin, shipped standalone as the `hermes-brain-memory`
27
+ pip package per upstream policy), **GitHub Copilot CLI** (plugin with
28
+ `sessionStart` context injection + skills; the repo is now a Copilot plugin
29
+ marketplace via `.github/plugin/marketplace.json` — install with
30
+ `copilot plugin install brain-memory@brain`), and **Kilo** (runtime plugin
31
+ with chat-message injection, session tracking, and `BRAIN_AGENT` labeling).
32
+ - **Two new installer runtimes.** `brain --copilot` (global prompt at
33
+ `~/.copilot/copilot-instructions.md`, skills in the cross-tool
34
+ `~/.agents/skills/`) and `brain --kilo` (prompt registered in the
35
+ `kilo.jsonc` `instructions` array via a safe strict-JSON editor; repo-local
36
+ `AGENTS.md` shared with Codex/OpenCode).
37
+
38
+ ### Fixed
39
+
40
+ - Kilo plugin derives the project label from `input.project` as well, so a
41
+ plugin host running with cwd `/` no longer records sessions as project
42
+ `"unknown"`.
43
+ - Hermes `cli.py` is a standalone diagnostics tool (`python3 cli.py
44
+ status|recall`) — Hermes exposes no CLI hook to user-installed memory
45
+ providers, so the previously documented `hermes memory recall` never
46
+ existed.
47
+ - Every `npm publish` now runs the full test suite via `prepublishOnly` —
48
+ the old `prerelease` script was a no-op vestige no release path invoked.
49
+
9
50
  ## [0.1.0-beta.31] - 2026-07-01
10
51
 
11
52
  ### Fixed
package/README.md CHANGED
@@ -40,6 +40,7 @@ Existing AI memory solutions use flat databases with tag-based retrieval. Brain
40
40
  - **Human-inspectable** — Browse your "brain" in any file explorer
41
41
  - **Git-friendly** — Full version history of how memories evolve
42
42
  - **Strength + decay** — Recalled memories get stronger, forgotten ones fade. Just like your brain
43
+ - **Recall receipts** — Memory that visibly fires: every answer shaped by a memory ends with a one-line attributable receipt (`◉ memory: "<title>" (<type>, <age>)`), minted by the engine so it can't be hallucinated
43
44
  - **Associative network** — Memories link to each other with weighted connections. Recalling one activates related ones automatically
44
45
  - **Context-dependent recall** — Memories encoded in a similar context to the current session are scored higher
45
46
  - **Spaced reinforcement** — Memories recalled after longer intervals get bigger boosts, cramming produces diminishing returns
package/bin/recall.js CHANGED
@@ -39,6 +39,8 @@ const {
39
39
  rankMemories,
40
40
  } = require('../src/scorer');
41
41
 
42
+ const { receiptFor } = require('../src/receipt');
43
+
42
44
  // Minimum relevance (or spreading bonus) for a memory to appear in explicit-
43
45
  // query results. Filters the zero/near-zero-relevance memories that would
44
46
  // otherwise pad the top-N purely on strength — an agent trusting those scores
@@ -140,19 +142,25 @@ function main() {
140
142
 
141
143
  // Return top N
142
144
  const top = args.top || 10;
143
- const results = ranked.slice(0, top).map((mem) => ({
144
- id: mem.id,
145
- title: mem.title || path.basename(mem.path, '.md'),
146
- path: mem.path,
147
- type: mem.type,
148
- score: mem.score,
149
- relevance: mem.relevance,
150
- decayed_strength: mem.decayed_strength,
151
- context_match: mem.context_match,
152
- spreading_bonus: mem.spreading_bonus,
153
- confidence: mem.confidence,
154
- tags: mem.tags,
155
- }));
145
+ const results = ranked.slice(0, top).map((mem) => {
146
+ const title = mem.title || path.basename(mem.path, '.md');
147
+ return {
148
+ id: mem.id,
149
+ title,
150
+ path: mem.path,
151
+ type: mem.type,
152
+ score: mem.score,
153
+ relevance: mem.relevance,
154
+ decayed_strength: mem.decayed_strength,
155
+ context_match: mem.context_match,
156
+ spreading_bonus: mem.spreading_bonus,
157
+ confidence: mem.confidence,
158
+ tags: mem.tags,
159
+ // Recall receipt — the engine mints it, agents copy it verbatim when
160
+ // this memory materially shapes an answer (so it can't be hallucinated).
161
+ receipt: receiptFor({ ...mem, title }),
162
+ };
163
+ });
156
164
 
157
165
  console.log(JSON.stringify(results, null, 2));
158
166
  }
@@ -42,6 +42,7 @@ const {
42
42
 
43
43
  const { rankMemories } = require('../src/scorer');
44
44
  const { advertisedSummaries } = require('../src/skills');
45
+ const { receiptFor } = require('../src/receipt');
45
46
 
46
47
  function parseArgs(argv) {
47
48
  const args = { project: null, topics: null, task: null, top: 5 };
@@ -63,6 +64,11 @@ function estimateTokens(entry) {
63
64
  return Math.ceil(((entry.title || '').length + 8) / 4);
64
65
  }
65
66
 
67
+ /** chars/4 token estimate for a minted receipt line (counted against budgets). */
68
+ function receiptTokens(receipt) {
69
+ return receipt ? Math.ceil(receipt.length / 4) : 0;
70
+ }
71
+
66
72
  /**
67
73
  * Tier B §10.4 — reorder an importance-sorted list so the top items land at the
68
74
  * edges (start + end), where models attend best, leaving the middle for lower
@@ -186,7 +192,8 @@ function computeSessionStart(projectRoot, args = {}) {
186
192
  let pinnedExcluded = 0;
187
193
  const pinCap = Math.min(config.pin_budget_tokens, cap);
188
194
  for (const c of pinnedCandidates) {
189
- const est = estimateTokens(c.entry);
195
+ const receipt = receiptFor(c.entry);
196
+ const est = estimateTokens(c.entry) + receiptTokens(receipt);
190
197
  if (pinnedTokens + est > pinCap && pinned.length > 0) { pinnedExcluded++; continue; }
191
198
  pinned.push({
192
199
  id: c.id,
@@ -195,6 +202,7 @@ function computeSessionStart(projectRoot, args = {}) {
195
202
  scope: c.scope,
196
203
  priority: c.priority,
197
204
  tokens: est,
205
+ receipt,
198
206
  });
199
207
  pinnedTokens += est;
200
208
  }
@@ -220,18 +228,21 @@ function computeSessionStart(projectRoot, args = {}) {
220
228
  let excluded = 0;
221
229
  for (const mem of ranked.slice(0, top)) {
222
230
  if (pinnedIds.has(mem.id)) continue; // already presented in the pinned tier
223
- const est = estimateTokens(mem);
231
+ const title = mem.title || path.basename(mem.path || '', '.md');
232
+ const receipt = receiptFor({ ...mem, title });
233
+ const est = estimateTokens(mem) + receiptTokens(receipt);
224
234
  if (used + est > recallCap && context_recall.length > 0) {
225
235
  excluded++;
226
236
  continue;
227
237
  }
228
238
  context_recall.push({
229
239
  id: mem.id,
230
- title: mem.title || path.basename(mem.path || '', '.md'),
240
+ title,
231
241
  path: mem.path,
232
242
  type: mem.type,
233
243
  score: mem.score,
234
244
  token_estimate: est,
245
+ receipt,
235
246
  });
236
247
  used += est;
237
248
  }
@@ -39,7 +39,7 @@ If the brain-memory package is installed globally, use:
39
39
  brain recall "$ARGUMENTS" --project "<project>" --task "<task_type>" --top 10
40
40
  ```
41
41
 
42
- The engine computes **TF-IDF relevance** (cosine similarity between query and memory content), then combines it with decayed strength, recency, spreading activation, context match, and salience using the v4 formula. All scoring is deterministic — same query always produces the same ranking.
42
+ The engine computes **TF-IDF relevance** (cosine similarity between query and memory content), then combines it with decayed strength, recency, spreading activation, context match, and salience using the v4 formula. All scoring is deterministic — same query always produces the same ranking. Each result also carries a pre-minted `receipt` line (`◉ memory: "<title>" (<type>, <age>)`) — keep it for step 6.
43
43
 
44
44
  ### 3. Read Top Memories
45
45
 
@@ -100,6 +100,7 @@ Format the output clearly. Include confidence indicators for low-confidence memo
100
100
 
101
101
  ---
102
102
  *Memory reinforced — strength updated, decay improved*
103
+ ◉ memory: "<title>" (<type>, <age>)
103
104
  ```
104
105
 
105
106
  For consolidated responses (Case B):
@@ -116,4 +117,10 @@ For consolidated responses (Case B):
116
117
 
117
118
  ---
118
119
  *<N> memories reinforced, association links strengthened*
120
+ ◉ memory: "<title>" (<type>, <age>)
121
+ ◉ memory: "<title>" (<type>, <age>)
119
122
  ```
123
+
124
+ ### 7. End With Receipts
125
+
126
+ End the reply with the `receipt` lines of the memories you actually presented, copied **verbatim** from the engine's `receipt` field — max 3, at the very end (as in the templates above). Never compose a receipt yourself: only lines the engine returned.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "brain-memory",
3
- "version": "0.1.0-beta.32",
3
+ "version": "0.1.0-beta.33",
4
4
  "description": "A brain-inspired hierarchical memory system for AI coding agents. Deep nested file structure that mimics human memory with time-decay and strength-based recall.",
5
5
  "keywords": [
6
6
  "claude-code",
@@ -44,13 +44,13 @@
44
44
  "url": "git+https://github.com/omelas-tech/brain.git"
45
45
  },
46
46
  "scripts": {
47
- "test": "node --test test/index-manager.test.js test/scorer.test.js test/tfidf.test.js test/recall.test.js test/recall-cli.test.js test/forget.test.js test/functional.test.js test/erasure.test.js test/stress.test.js test/crypto.test.js test/git-sync.test.js test/cloud-sync.test.js test/export-import.test.js test/install.test.js test/prompts.test.js test/session-start.test.js test/memorize.test.js test/pinning.test.js test/skills.test.js test/contradiction.test.js",
47
+ "test": "node --test test/index-manager.test.js test/scorer.test.js test/tfidf.test.js test/receipt.test.js test/recall.test.js test/recall-cli.test.js test/forget.test.js test/functional.test.js test/erasure.test.js test/stress.test.js test/crypto.test.js test/git-sync.test.js test/cloud-sync.test.js test/export-import.test.js test/install.test.js test/prompts.test.js test/session-start.test.js test/memorize.test.js test/pinning.test.js test/skills.test.js test/contradiction.test.js",
48
48
  "test:integrations": "npm run test:integrations:openclaw && npm run test:integrations:copilot && npm run test:integrations:kilo && npm run test:integrations:hermes",
49
49
  "test:integrations:openclaw": "node --test integrations/openclaw/test/*.test.mjs",
50
50
  "test:integrations:copilot": "node --test integrations/copilot/test/*.test.mjs",
51
51
  "test:integrations:kilo": "node --test integrations/kilo/test/*.test.mjs",
52
52
  "test:integrations:hermes": "python3 -m unittest discover -s integrations/hermes/tests",
53
- "prerelease": "npm test && npm run test:integrations",
53
+ "prepublishOnly": "npm test && npm run test:integrations",
54
54
  "changelog": "node scripts/release.mjs",
55
55
  "changelog:status": "node scripts/release.mjs status",
56
56
  "release:beta": "npm version prerelease --preid beta && npm publish --tag beta && npm dist-tag add brain-memory@$(node -p \"require('./package.json').version\") latest",
@@ -170,6 +170,14 @@ When the user asks you to "remember" something, or when context from past sessio
170
170
 
171
171
  The recall engine ensures **identical scoring across all agents** — Claude, Gemini, and Codex all get the same rankings for the same query.
172
172
 
173
+ ## Recall Receipts
174
+
175
+ Every memory returned by `brain recall` and by the session-start payload (each `context_recall` and `pinned` entry) carries a pre-minted `receipt` field: `◉ memory: "<title>" (<type>, <age>)`. Receipts make memory visibly fire — the user sees exactly which memory shaped an answer.
176
+
177
+ - When recalled or pinned memories **materially shaped your answer**, end the response with their `receipt` lines, copied **verbatim** — max 3 lines, at the very end.
178
+ - Only receipt what actually influenced the output. Pinned memories get a receipt only when they were decisive for this specific answer — they are always present, and receipting them every turn is spam.
179
+ - No memory used → no receipt line. Never fabricate a receipt for a memory the engine did not return; only lines provided in `receipt` fields.
180
+
173
181
  ## Portable Sync
174
182
 
175
183
  Brain memories can be synced across devices in two ways:
package/prompts/claude.md CHANGED
@@ -169,6 +169,14 @@ When the user asks you to "remember" something, or when context from past sessio
169
169
 
170
170
  The recall engine ensures **identical scoring across all agents** — Claude, Gemini, and Codex all get the same rankings for the same query.
171
171
 
172
+ ## Recall Receipts
173
+
174
+ Every memory returned by `brain recall` and by the session-start payload (each `context_recall` and `pinned` entry) carries a pre-minted `receipt` field: `◉ memory: "<title>" (<type>, <age>)`. Receipts make memory visibly fire — the user sees exactly which memory shaped an answer.
175
+
176
+ - When recalled or pinned memories **materially shaped your answer**, end the response with their `receipt` lines, copied **verbatim** — max 3 lines, at the very end.
177
+ - Only receipt what actually influenced the output. Pinned memories get a receipt only when they were decisive for this specific answer — they are always present, and receipting them every turn is spam.
178
+ - No memory used → no receipt line. Never fabricate a receipt for a memory the engine did not return; only lines provided in `receipt` fields.
179
+
172
180
  ## Portable Sync
173
181
 
174
182
  Brain memories can be synced across devices in two ways:
@@ -172,6 +172,14 @@ When the user asks you to "remember" something, or when context from past sessio
172
172
 
173
173
  The recall engine ensures **identical scoring across all agents** — Claude, Codex, and Copilot all get the same rankings for the same query.
174
174
 
175
+ ## Recall Receipts
176
+
177
+ Every memory returned by `brain recall` and by the session-start payload (each `context_recall` and `pinned` entry) carries a pre-minted `receipt` field: `◉ memory: "<title>" (<type>, <age>)`. Receipts make memory visibly fire — the user sees exactly which memory shaped an answer.
178
+
179
+ - When recalled or pinned memories **materially shaped your answer**, end the response with their `receipt` lines, copied **verbatim** — max 3 lines, at the very end.
180
+ - Only receipt what actually influenced the output. Pinned memories get a receipt only when they were decisive for this specific answer — they are always present, and receipting them every turn is spam.
181
+ - No memory used → no receipt line. Never fabricate a receipt for a memory the engine did not return; only lines provided in `receipt` fields.
182
+
175
183
  ## Portable Sync
176
184
 
177
185
  Brain memories can be synced across devices in two ways:
package/prompts/kilo.md CHANGED
@@ -171,6 +171,14 @@ When the user asks you to "remember" something, or when context from past sessio
171
171
 
172
172
  The recall engine ensures **identical scoring across all agents** — Claude, Gemini, Codex, and OpenCode all get the same rankings for the same query.
173
173
 
174
+ ## Recall Receipts
175
+
176
+ Every memory returned by `brain recall` and by the session-start payload (each `context_recall` and `pinned` entry) carries a pre-minted `receipt` field: `◉ memory: "<title>" (<type>, <age>)`. Receipts make memory visibly fire — the user sees exactly which memory shaped an answer.
177
+
178
+ - When recalled or pinned memories **materially shaped your answer**, end the response with their `receipt` lines, copied **verbatim** — max 3 lines, at the very end.
179
+ - Only receipt what actually influenced the output. Pinned memories get a receipt only when they were decisive for this specific answer — they are always present, and receipting them every turn is spam.
180
+ - No memory used → no receipt line. Never fabricate a receipt for a memory the engine did not return; only lines provided in `receipt` fields.
181
+
174
182
  ## Portable Sync
175
183
 
176
184
  Brain memories can be synced across devices in two ways:
package/prompts/openai.md CHANGED
@@ -170,6 +170,14 @@ When the user asks you to "remember" something, or when context from past sessio
170
170
 
171
171
  The recall engine ensures **identical scoring across all agents** — Claude, Gemini, and Codex all get the same rankings for the same query.
172
172
 
173
+ ## Recall Receipts
174
+
175
+ Every memory returned by `brain recall` and by the session-start payload (each `context_recall` and `pinned` entry) carries a pre-minted `receipt` field: `◉ memory: "<title>" (<type>, <age>)`. Receipts make memory visibly fire — the user sees exactly which memory shaped an answer.
176
+
177
+ - When recalled or pinned memories **materially shaped your answer**, end the response with their `receipt` lines, copied **verbatim** — max 3 lines, at the very end.
178
+ - Only receipt what actually influenced the output. Pinned memories get a receipt only when they were decisive for this specific answer — they are always present, and receipting them every turn is spam.
179
+ - No memory used → no receipt line. Never fabricate a receipt for a memory the engine did not return; only lines provided in `receipt` fields.
180
+
173
181
  ## Portable Sync
174
182
 
175
183
  Brain memories can be synced across devices in two ways:
@@ -169,6 +169,14 @@ When the user asks you to "remember" something, or when context from past sessio
169
169
 
170
170
  The recall engine ensures **identical scoring across all agents** — Claude, Gemini, Codex, and OpenCode all get the same rankings for the same query.
171
171
 
172
+ ## Recall Receipts
173
+
174
+ Every memory returned by `brain recall` and by the session-start payload (each `context_recall` and `pinned` entry) carries a pre-minted `receipt` field: `◉ memory: "<title>" (<type>, <age>)`. Receipts make memory visibly fire — the user sees exactly which memory shaped an answer.
175
+
176
+ - When recalled or pinned memories **materially shaped your answer**, end the response with their `receipt` lines, copied **verbatim** — max 3 lines, at the very end.
177
+ - Only receipt what actually influenced the output. Pinned memories get a receipt only when they were decisive for this specific answer — they are always present, and receipting them every turn is spam.
178
+ - No memory used → no receipt line. Never fabricate a receipt for a memory the engine did not return; only lines provided in `receipt` fields.
179
+
172
180
  ## Portable Sync
173
181
 
174
182
  Brain memories can be synced across devices in two ways:
package/src/receipt.js ADDED
@@ -0,0 +1,68 @@
1
+ /**
2
+ * Brain Memory — Recall Receipts
3
+ *
4
+ * Mints the one-line attributable receipt attached to every memory the
5
+ * engine returns (bin/recall.js results, bin/session-start.js context_recall
6
+ * and pinned entries). Agents copy the line VERBATIM at the end of any
7
+ * response a memory materially shaped — because the engine mints it, a
8
+ * receipt can never be hallucinated.
9
+ *
10
+ * Format: ◉ memory: "<title>" (<type>, <age>)
11
+ *
12
+ * Age is derived from the memory's `created` timestamp (falling back to
13
+ * `last_accessed`; omitted entirely when neither parses):
14
+ * today | yesterday | <N>d ago (2-30 days) | <N>mo ago (31-364 days,
15
+ * nearest month, min 1) | <N>y ago (365+ days, nearest year, min 1)
16
+ *
17
+ * Deterministic: `now` is injectable for tests.
18
+ */
19
+
20
+ const MS_PER_DAY = 24 * 60 * 60 * 1000;
21
+ const DAYS_PER_MONTH = 30.44; // mean Gregorian month
22
+ const DAYS_PER_YEAR = 365.25;
23
+ const MAX_TITLE_CHARS = 80;
24
+
25
+ /**
26
+ * Human age label for a timestamp, relative to `now`.
27
+ *
28
+ * @param {string|Date} timestamp - ISO timestamp (memory `created`)
29
+ * @param {Date} now - Reference time
30
+ * @returns {string|null} Age label, or null when the timestamp is invalid
31
+ */
32
+ function ageLabel(timestamp, now) {
33
+ const then = new Date(timestamp);
34
+ if (Number.isNaN(then.getTime())) return null;
35
+ const days = Math.floor((now.getTime() - then.getTime()) / MS_PER_DAY);
36
+ if (days <= 0) return 'today';
37
+ if (days === 1) return 'yesterday';
38
+ if (days <= 30) return `${days}d ago`;
39
+ if (days <= 364) return `${Math.max(1, Math.round(days / DAYS_PER_MONTH))}mo ago`;
40
+ return `${Math.max(1, Math.round(days / DAYS_PER_YEAR))}y ago`;
41
+ }
42
+
43
+ /**
44
+ * Mint the receipt line for a memory-like object ({title, type, created,
45
+ * last_accessed}). Title is used as-is (truncated at 77 chars + "…" only
46
+ * when longer than 80); `created` falls back to `last_accessed`, and the
47
+ * age segment is omitted when neither parses.
48
+ *
49
+ * @param {Object} memoryLike - Object with title/type/created/last_accessed
50
+ * @param {Function} [nowFn] - Injectable clock for deterministic tests
51
+ * @returns {string} The receipt line
52
+ */
53
+ function receiptFor(memoryLike, nowFn) {
54
+ const mem = memoryLike || {};
55
+ const now = (nowFn || (() => new Date()))();
56
+
57
+ let title = typeof mem.title === 'string' && mem.title ? mem.title : 'memory';
58
+ if (title.length > MAX_TITLE_CHARS) title = title.slice(0, 77) + '…';
59
+
60
+ const type = typeof mem.type === 'string' && mem.type ? mem.type : 'memory';
61
+ const age = ageLabel(mem.created ?? mem.last_accessed ?? NaN, now);
62
+
63
+ return age
64
+ ? `◉ memory: "${title}" (${type}, ${age})`
65
+ : `◉ memory: "${title}" (${type})`;
66
+ }
67
+
68
+ module.exports = { receiptFor, ageLabel };