agent-knowledge 1.3.26 → 1.4.0

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.
Files changed (52) hide show
  1. package/CHANGELOG.md +36 -0
  2. package/README.md +6 -1
  3. package/agent-desk-plugin.json +1 -1
  4. package/dist/dashboard.d.ts.map +1 -1
  5. package/dist/dashboard.js +9 -2
  6. package/dist/dashboard.js.map +1 -1
  7. package/dist/knowledge/graph.d.ts +21 -4
  8. package/dist/knowledge/graph.d.ts.map +1 -1
  9. package/dist/knowledge/graph.js +71 -15
  10. package/dist/knowledge/graph.js.map +1 -1
  11. package/dist/knowledge/search.d.ts +13 -0
  12. package/dist/knowledge/search.d.ts.map +1 -1
  13. package/dist/knowledge/search.js +13 -3
  14. package/dist/knowledge/search.js.map +1 -1
  15. package/dist/search/boosts.d.ts +63 -0
  16. package/dist/search/boosts.d.ts.map +1 -0
  17. package/dist/search/boosts.js +214 -0
  18. package/dist/search/boosts.js.map +1 -0
  19. package/dist/server.d.ts.map +1 -1
  20. package/dist/server.js +53 -13
  21. package/dist/server.js.map +1 -1
  22. package/dist/sessions/indexer.d.ts +3 -0
  23. package/dist/sessions/indexer.d.ts.map +1 -1
  24. package/dist/sessions/indexer.js +9 -1
  25. package/dist/sessions/indexer.js.map +1 -1
  26. package/dist/sessions/search.d.ts.map +1 -1
  27. package/dist/sessions/search.js +9 -1
  28. package/dist/sessions/search.js.map +1 -1
  29. package/dist/tool-handlers.d.ts.map +1 -1
  30. package/dist/tool-handlers.js +61 -8
  31. package/dist/tool-handlers.js.map +1 -1
  32. package/dist/types.d.ts +8 -0
  33. package/dist/types.d.ts.map +1 -1
  34. package/dist/types.js +5 -0
  35. package/dist/types.js.map +1 -1
  36. package/dist/ui/render-sessions.js +3 -1
  37. package/dist/vectorstore/chunker.d.ts +13 -1
  38. package/dist/vectorstore/chunker.d.ts.map +1 -1
  39. package/dist/vectorstore/chunker.js +8 -1
  40. package/dist/vectorstore/chunker.js.map +1 -1
  41. package/dist/vectorstore/store.d.ts +20 -0
  42. package/dist/vectorstore/store.d.ts.map +1 -1
  43. package/dist/vectorstore/store.js +92 -0
  44. package/dist/vectorstore/store.js.map +1 -1
  45. package/dist/wakeup.d.ts +37 -0
  46. package/dist/wakeup.d.ts.map +1 -0
  47. package/dist/wakeup.js +132 -0
  48. package/dist/wakeup.js.map +1 -0
  49. package/docs/USER-MANUAL.md +31 -10
  50. package/package.json +3 -1
  51. package/scripts/hooks/precompact-flush.mjs +174 -0
  52. package/scripts/prune-now.mjs +21 -0
@@ -0,0 +1,37 @@
1
+ /**
2
+ * wakeup — return a tiny "L0 + L1" context blob at session start.
3
+ *
4
+ * Exposed via the MCP `knowledge` tool as `action: "wakeup"` (no separate tool).
5
+ *
6
+ * Modeled after mempalace's `layers.py`:
7
+ * L0 = identity (~100 tokens, always loaded, plain text)
8
+ * L1 = essential facts — top-N highest-weight knowledge entries
9
+ *
10
+ * The whole blob is bounded by a token budget (chars/4 estimate). Designed
11
+ * to be called once at session start so the agent has a small but well-chosen
12
+ * window into the user's world before it ever issues a real search.
13
+ */
14
+ export interface WakeupOptions {
15
+ /** Max total tokens (chars/4) for the rendered blob. Default 800. */
16
+ tokenBudget?: number;
17
+ /** Optional category filter for L1 (e.g. only `projects`). */
18
+ scope?: string;
19
+ }
20
+ export interface WakeupResult {
21
+ identity: string;
22
+ entries: Array<{
23
+ path: string;
24
+ title: string;
25
+ weight: number;
26
+ excerpt: string;
27
+ }>;
28
+ rendered: string;
29
+ token_estimate: number;
30
+ truncated: boolean;
31
+ }
32
+ /**
33
+ * Build the wakeup payload.
34
+ * Greedily includes top-weighted entries until the token budget is hit.
35
+ */
36
+ export declare function wakeup(options?: WakeupOptions): WakeupResult;
37
+ //# sourceMappingURL=wakeup.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"wakeup.d.ts","sourceRoot":"","sources":["../src/wakeup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAOH,MAAM,WAAW,aAAa;IAC5B,qEAAqE;IACrE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,KAAK,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,OAAO,CAAC;CACpB;AAyED;;;GAGG;AACH,wBAAgB,MAAM,CAAC,OAAO,GAAE,aAAkB,GAAG,YAAY,CAuDhE"}
package/dist/wakeup.js ADDED
@@ -0,0 +1,132 @@
1
+ /**
2
+ * wakeup — return a tiny "L0 + L1" context blob at session start.
3
+ *
4
+ * Exposed via the MCP `knowledge` tool as `action: "wakeup"` (no separate tool).
5
+ *
6
+ * Modeled after mempalace's `layers.py`:
7
+ * L0 = identity (~100 tokens, always loaded, plain text)
8
+ * L1 = essential facts — top-N highest-weight knowledge entries
9
+ *
10
+ * The whole blob is bounded by a token budget (chars/4 estimate). Designed
11
+ * to be called once at session start so the agent has a small but well-chosen
12
+ * window into the user's world before it ever issues a real search.
13
+ */
14
+ import fs from 'fs';
15
+ import path from 'path';
16
+ import { listEntries, readEntry } from './knowledge/store.js';
17
+ import { getConfig } from './types.js';
18
+ const DEFAULT_BUDGET = 800;
19
+ const CHARS_PER_TOKEN = 4;
20
+ const L1_EXCERPT_CHARS = 240;
21
+ const DEFAULT_IDENTITY = `## L0 — IDENTITY
22
+ No identity configured.
23
+ Create ~/agent-knowledge/identity.md to populate Layer 0.
24
+ Suggested fields: who you are, your primary role, the people you work with, the projects you maintain.`;
25
+ function loadIdentity(memoryDir) {
26
+ const candidates = [path.join(memoryDir, 'identity.md'), path.join(memoryDir, 'IDENTITY.md')];
27
+ for (const p of candidates) {
28
+ try {
29
+ if (fs.existsSync(p)) {
30
+ return fs.readFileSync(p, 'utf-8').trim();
31
+ }
32
+ }
33
+ catch {
34
+ // ignore — fall through
35
+ }
36
+ }
37
+ return DEFAULT_IDENTITY;
38
+ }
39
+ /**
40
+ * Weight = recency * log(size + 1).
41
+ * No frontmatter weight field exists today, so we use mtime + body size as a
42
+ * proxy for "this entry is large and recently touched, therefore important".
43
+ */
44
+ function weighEntries(memoryDir, scope) {
45
+ const entries = listEntries(memoryDir, scope);
46
+ const now = Date.now();
47
+ const scored = [];
48
+ for (const entry of entries) {
49
+ try {
50
+ const fullPath = path.join(memoryDir, entry.path);
51
+ const stat = fs.statSync(fullPath);
52
+ const { content } = readEntry(memoryDir, entry.path);
53
+ const ageDays = Math.max(1, (now - stat.mtimeMs) / (24 * 3600_000));
54
+ // Recency factor decays over ~90 days; size factor uses log to avoid huge files dominating.
55
+ const recency = Math.exp(-ageDays / 90);
56
+ const sizeFactor = Math.log(stat.size + 1);
57
+ const weight = recency * sizeFactor;
58
+ scored.push({
59
+ path: entry.path,
60
+ title: entry.title || entry.path,
61
+ weight,
62
+ content,
63
+ });
64
+ }
65
+ catch {
66
+ continue;
67
+ }
68
+ }
69
+ scored.sort((a, b) => b.weight - a.weight);
70
+ return scored;
71
+ }
72
+ function shortExcerpt(content, maxChars) {
73
+ const cleaned = content.replace(/\s+/g, ' ').trim();
74
+ if (cleaned.length <= maxChars)
75
+ return cleaned;
76
+ return cleaned.slice(0, maxChars).trimEnd() + '…';
77
+ }
78
+ /**
79
+ * Build the wakeup payload.
80
+ * Greedily includes top-weighted entries until the token budget is hit.
81
+ */
82
+ export function wakeup(options = {}) {
83
+ const tokenBudget = options.tokenBudget ?? DEFAULT_BUDGET;
84
+ const charBudget = tokenBudget * CHARS_PER_TOKEN;
85
+ const config = getConfig();
86
+ const identity = loadIdentity(config.memoryDir);
87
+ const identityChars = identity.length + 16; // header overhead
88
+ let used = identityChars;
89
+ const scored = weighEntries(config.memoryDir, options.scope);
90
+ const included = [];
91
+ let truncated = false;
92
+ for (const entry of scored) {
93
+ const excerpt = shortExcerpt(entry.content, L1_EXCERPT_CHARS);
94
+ const lineCost = excerpt.length + entry.title.length + entry.path.length + 12;
95
+ if (used + lineCost > charBudget) {
96
+ truncated = true;
97
+ break;
98
+ }
99
+ included.push({
100
+ path: entry.path,
101
+ title: entry.title,
102
+ weight: Math.round(entry.weight * 100) / 100,
103
+ excerpt,
104
+ });
105
+ used += lineCost;
106
+ }
107
+ const lines = [];
108
+ lines.push(identity);
109
+ lines.push('');
110
+ lines.push('## L1 — ESSENTIAL FACTS');
111
+ if (included.length === 0) {
112
+ lines.push('_No entries indexed. Write some via `knowledge` action=write to populate Layer 1._');
113
+ }
114
+ else {
115
+ for (const e of included) {
116
+ lines.push(`- **${e.title}** (\`${e.path}\`) — ${e.excerpt}`);
117
+ }
118
+ }
119
+ if (truncated) {
120
+ lines.push('');
121
+ lines.push('_(L1 truncated to fit token budget — call `knowledge_search` for the rest.)_');
122
+ }
123
+ const rendered = lines.join('\n');
124
+ return {
125
+ identity,
126
+ entries: included,
127
+ rendered,
128
+ token_estimate: Math.ceil(rendered.length / CHARS_PER_TOKEN),
129
+ truncated,
130
+ };
131
+ }
132
+ //# sourceMappingURL=wakeup.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"wakeup.js","sourceRoot":"","sources":["../src/wakeup.ts"],"names":[],"mappings":"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"}
@@ -193,20 +193,21 @@ agent-knowledge exposes 6 MCP tools, each with multiple actions.
193
193
 
194
194
  ### knowledge
195
195
 
196
- Knowledge base CRUD and git sync.
196
+ Knowledge base CRUD, git sync, and session-start hydration.
197
197
 
198
- **Actions:** `list`, `read`, `write`, `delete`, `sync`
198
+ **Actions:** `list`, `read`, `write`, `delete`, `sync`, `wakeup`
199
199
 
200
200
  **Parameters:**
201
201
 
202
- | Name | Type | Required | Description |
203
- | ---------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------- |
204
- | `action` | string | Yes | One of: `list`, `read`, `write`, `delete`, `sync` |
205
- | `category` | string | No | [list] Filter by category; [write] Target directory. One of: `projects`, `people`, `decisions`, `workflows`, `notes` |
206
- | `tag` | string | No | [list] Filter by tag |
207
- | `path` | string | No | [read/delete] Relative path, e.g. `projects/my-project.md` |
208
- | `filename` | string | No | [write] Filename with or without .md extension |
209
- | `content` | string | No | [write] Full Markdown content (max 1MB) |
202
+ | Name | Type | Required | Description |
203
+ | -------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------- |
204
+ | `action` | string | Yes | One of: `list`, `read`, `write`, `delete`, `sync`, `wakeup` |
205
+ | `category` | string | No | [list/wakeup] Filter by category; [write] Target directory. One of: `projects`, `people`, `decisions`, `workflows`, `notes` |
206
+ | `tag` | string | No | [list] Filter by tag |
207
+ | `path` | string | No | [read/delete] Relative path, e.g. `projects/my-project.md` |
208
+ | `filename` | string | No | [write] Filename with or without .md extension |
209
+ | `content` | string | No | [write] Full Markdown content (max 1MB) |
210
+ | `token_budget` | number | No | [wakeup] Max tokens for the rendered L0+L1 blob (chars/4 estimate, default 800, range 50–8000) |
210
211
 
211
212
  **Action: list**
212
213
 
@@ -257,6 +258,26 @@ Manual git pull + push.
257
258
  knowledge with action "sync"
258
259
  ```
259
260
 
261
+ **Action: wakeup**
262
+
263
+ Return a small "L0 + L1" context blob: identity (from `~/agent-knowledge/identity.md`) plus the highest-weighted entries, fit under a token budget. Modeled after the mempalace layered-memory approach. Call once at session start so the agent has its world loaded before issuing any real search.
264
+
265
+ Weight = `recency × log(size+1)` — recently-edited and substantial entries float to the top. The blob is rendered as Markdown with one bullet per L1 entry; each bullet is a short excerpt.
266
+
267
+ ```
268
+ knowledge with action "wakeup"
269
+ knowledge with action "wakeup", token_budget 1200
270
+ knowledge with action "wakeup", category "projects"
271
+ ```
272
+
273
+ **Response:**
274
+
275
+ - `identity` — text from `identity.md`, or a default placeholder.
276
+ - `entries` — array of `{ path, title, weight, excerpt }`, top-weighted first.
277
+ - `rendered` — the assembled Markdown blob ready to paste into a system prompt.
278
+ - `token_estimate` — `chars / 4`.
279
+ - `truncated` — `true` when the budget cut off the L1 list.
280
+
260
281
  ---
261
282
 
262
283
  ### knowledge_search
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agent-knowledge",
3
- "version": "1.3.26",
3
+ "version": "1.4.0",
4
4
  "description": "Cross-session memory and recall for AI agents — git-synced knowledge base, knowledge graph, confidence scoring, hybrid semantic+TF-IDF search, auto-distillation with secrets scrubbing",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -37,6 +37,7 @@
37
37
  "dev": "tsc --watch",
38
38
  "test": "vitest run",
39
39
  "test:watch": "vitest",
40
+ "bench": "tsx bench/run.ts",
40
41
  "test:coverage": "vitest run --coverage",
41
42
  "lint": "eslint src/ tests/",
42
43
  "lint:fix": "eslint src/ tests/ --fix",
@@ -89,6 +90,7 @@
89
90
  "husky": "^9.0.0",
90
91
  "lint-staged": "^16.0.0",
91
92
  "prettier": "^3.8.1",
93
+ "tsx": "^4.21.0",
92
94
  "typescript": "^5.7.0",
93
95
  "typescript-eslint": "^8.57.2",
94
96
  "vitest": "^3.0.0"
@@ -0,0 +1,174 @@
1
+ #!/usr/bin/env node
2
+
3
+ // =============================================================================
4
+ // agent-knowledge PreCompact / Stop hook
5
+ //
6
+ // Flushes a session summary to ~/agent-knowledge/sessions/ before the host
7
+ // (Claude Code, Cursor, Codex CLI, etc.) compacts or ends the conversation,
8
+ // so the verbatim distillation has something to anchor against later.
9
+ //
10
+ // Modeled after mempalace's `mempal_precompact_hook.sh`. Fail-open: any error
11
+ // is logged to stderr and the hook still prints `{}` so it never blocks the host.
12
+ //
13
+ // Wire-up (host-specific — examples):
14
+ //
15
+ // Claude Code (~/.claude/settings.json):
16
+ // {
17
+ // "hooks": {
18
+ // "PreCompact": [{"matcher": "", "hooks": [
19
+ // {"type": "command",
20
+ // "command": "node \"$HOME/.claude/mcp-servers/agent-knowledge/scripts/hooks/precompact-flush.mjs\"",
21
+ // "timeout": 10}
22
+ // ]}],
23
+ // "Stop": [{"matcher": "", "hooks": [
24
+ // {"type": "command",
25
+ // "command": "node \"$HOME/.claude/mcp-servers/agent-knowledge/scripts/hooks/precompact-flush.mjs\"",
26
+ // "timeout": 10}
27
+ // ]}]
28
+ // }
29
+ // }
30
+ //
31
+ // Reads hook JSON from stdin (the host pipes it). The fields we look at:
32
+ // { session_id, hook_event_name, cwd? }
33
+ // =============================================================================
34
+
35
+ import { fileURLToPath } from 'url';
36
+ import { dirname, join, resolve } from 'path';
37
+ import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'fs';
38
+ import { homedir } from 'os';
39
+
40
+ const __filename = fileURLToPath(import.meta.url);
41
+ const __dirname = dirname(__filename);
42
+
43
+ function fail(msg) {
44
+ process.stderr.write(`[precompact-flush] ${msg}\n`);
45
+ process.stdout.write('{}\n');
46
+ process.exit(0);
47
+ }
48
+
49
+ function ok() {
50
+ process.stdout.write('{}\n');
51
+ process.exit(0);
52
+ }
53
+
54
+ async function readStdin() {
55
+ return new Promise((resolveP) => {
56
+ let data = '';
57
+ if (process.stdin.isTTY) return resolveP('');
58
+ process.stdin.setEncoding('utf-8');
59
+ process.stdin.on('data', (chunk) => (data += chunk));
60
+ process.stdin.on('end', () => resolveP(data));
61
+ // Don't hang forever if the host doesn't pipe anything
62
+ setTimeout(() => resolveP(data), 2000);
63
+ });
64
+ }
65
+
66
+ function slugify(input) {
67
+ return (input || 'session')
68
+ .toLowerCase()
69
+ .replace(/[^a-z0-9]+/g, '-')
70
+ .replace(/^-+|-+$/g, '')
71
+ .slice(0, 60);
72
+ }
73
+
74
+ function memoryDir() {
75
+ return process.env.KNOWLEDGE_MEMORY_DIR || join(homedir(), 'agent-knowledge');
76
+ }
77
+
78
+ async function main() {
79
+ const raw = await readStdin();
80
+ let payload = {};
81
+ if (raw) {
82
+ try {
83
+ payload = JSON.parse(raw);
84
+ } catch {
85
+ // Ignore — host may not have piped JSON
86
+ }
87
+ }
88
+
89
+ const sessionId = payload.session_id || process.env.CLAUDE_SESSION_ID || 'unknown';
90
+ const event = payload.hook_event_name || 'precompact';
91
+ const cwd = payload.cwd || process.cwd();
92
+ const projectSlug = slugify(cwd.split(/[\\/]/).filter(Boolean).pop() || 'project');
93
+
94
+ // Try to import the agent-knowledge summary helper directly (ESM dynamic import).
95
+ // The compiled output lives next to this script: ../../dist/sessions/summary.js
96
+ const distSummary = resolve(__dirname, '..', '..', 'dist', 'sessions', 'summary.js');
97
+ if (!existsSync(distSummary)) {
98
+ return fail(`dist not built: ${distSummary} (run \`npm run build\`)`);
99
+ }
100
+
101
+ let summaryFn;
102
+ try {
103
+ const mod = await import(`file://${distSummary.replace(/\\/g, '/')}`);
104
+ summaryFn = mod.getSessionSummary;
105
+ } catch (err) {
106
+ return fail(`import failed: ${err?.message || err}`);
107
+ }
108
+ if (typeof summaryFn !== 'function') {
109
+ return fail('getSessionSummary not exported from dist/sessions/summary.js');
110
+ }
111
+
112
+ let summary;
113
+ try {
114
+ summary = summaryFn(sessionId);
115
+ } catch (err) {
116
+ return fail(`getSessionSummary threw: ${err?.message || err}`);
117
+ }
118
+ if (!summary) {
119
+ return fail(`session ${sessionId} not found — nothing to flush`);
120
+ }
121
+
122
+ const outDir = join(memoryDir(), 'sessions', projectSlug);
123
+ try {
124
+ mkdirSync(outDir, { recursive: true });
125
+ } catch (err) {
126
+ return fail(`mkdir ${outDir}: ${err?.message || err}`);
127
+ }
128
+
129
+ const stamp = new Date().toISOString().replace(/[:.]/g, '-');
130
+ const outPath = join(outDir, `${event}-${stamp}-${sessionId.slice(0, 8)}.md`);
131
+
132
+ const body = [
133
+ '---',
134
+ `session_id: ${sessionId}`,
135
+ `event: ${event}`,
136
+ `flushed_at: ${new Date().toISOString()}`,
137
+ `cwd: ${cwd}`,
138
+ '---',
139
+ '',
140
+ `# Session ${sessionId}`,
141
+ '',
142
+ typeof summary === 'string'
143
+ ? summary
144
+ : '```json\n' + JSON.stringify(summary, null, 2) + '\n```',
145
+ '',
146
+ ].join('\n');
147
+
148
+ try {
149
+ writeFileSync(outPath, body, 'utf-8');
150
+ } catch (err) {
151
+ return fail(`write ${outPath}: ${err?.message || err}`);
152
+ }
153
+
154
+ process.stderr.write(`[precompact-flush] wrote ${outPath}\n`);
155
+
156
+ // Best-effort: append a one-line breadcrumb readable later by `knowledge` action=list
157
+ try {
158
+ const breadcrumb = join(memoryDir(), 'sessions', 'index.md');
159
+ const existing = existsSync(breadcrumb)
160
+ ? readFileSync(breadcrumb, 'utf-8')
161
+ : '# Session flushes\n';
162
+ writeFileSync(
163
+ breadcrumb,
164
+ existing + `- ${event} ${stamp} ${sessionId} → ${outPath}\n`,
165
+ 'utf-8',
166
+ );
167
+ } catch {
168
+ /* ignore */
169
+ }
170
+
171
+ ok();
172
+ }
173
+
174
+ main().catch((err) => fail(err?.message || String(err)));
@@ -0,0 +1,21 @@
1
+ import { VectorStore } from '../dist/vectorstore/index.js';
2
+ import { listSessions } from '../dist/sessions/summary.js';
3
+
4
+ const store = new VectorStore();
5
+ const before = store.stats();
6
+ console.log(`Before: ${before.uniqueSessions} indexed sessions, ${before.dbSizeMB} MB`);
7
+
8
+ const live = new Set(listSessions().map((s) => s.sessionId));
9
+ console.log(`Live sessions on disk: ${live.size}`);
10
+
11
+ const pruned = store.pruneOrphanSessions(live);
12
+ console.log(`Pruned: ${pruned.sessions} session(s), ${pruned.chunks} chunk(s)`);
13
+
14
+ const vac = store.vacuum();
15
+ console.log(
16
+ `VACUUM: ${(vac.beforeBytes / 1024 / 1024).toFixed(1)} MB -> ${(vac.afterBytes / 1024 / 1024).toFixed(1)} MB (reclaimed ${(vac.reclaimedBytes / 1024 / 1024).toFixed(1)} MB)`,
17
+ );
18
+
19
+ const after = store.stats();
20
+ console.log(`After: ${after.uniqueSessions} indexed sessions, ${after.dbSizeMB} MB`);
21
+ store.close();