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 +41 -0
- package/README.md +1 -0
- package/bin/recall.js +21 -13
- package/bin/session-start.js +14 -3
- package/commands/brain/remember.md +8 -1
- package/package.json +3 -3
- package/prompts/antigravity.md +8 -0
- package/prompts/claude.md +8 -0
- package/prompts/copilot.md +8 -0
- package/prompts/kilo.md +8 -0
- package/prompts/openai.md +8 -0
- package/prompts/opencode.md +8 -0
- package/src/receipt.js +68 -0
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
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
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
|
}
|
package/bin/session-start.js
CHANGED
|
@@ -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
|
|
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
|
|
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
|
|
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.
|
|
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
|
-
"
|
|
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",
|
package/prompts/antigravity.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:
|
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:
|
package/prompts/copilot.md
CHANGED
|
@@ -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:
|
package/prompts/opencode.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, 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 };
|