claude-db 0.2.3 → 0.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.
- package/README.md +17 -4
- package/dist/capture/flush.d.ts +20 -1
- package/dist/capture/flush.js +45 -5
- package/dist/capture/git.d.ts +2 -0
- package/dist/capture/git.js +96 -0
- package/dist/capture/index.d.ts +4 -3
- package/dist/capture/index.js +4 -3
- package/dist/capture/manual.d.ts +9 -0
- package/dist/capture/manual.js +0 -0
- package/dist/capture/transcript.d.ts +8 -0
- package/dist/capture/transcript.js +30 -0
- package/dist/capture/turn-extractor.d.ts +9 -1
- package/dist/capture/turn-extractor.js +74 -13
- package/dist/cli/index.js +421 -27
- package/dist/cli/install.d.ts +8 -0
- package/dist/cli/install.js +31 -0
- package/dist/mcp/render.d.ts +23 -0
- package/dist/mcp/render.js +78 -0
- package/dist/mcp/server.d.ts +1 -7
- package/dist/mcp/server.js +73 -36
- package/dist/store/adapter.d.ts +10 -0
- package/dist/store/adapter.js +8 -0
- package/dist/store/mongo/index.d.ts +1 -0
- package/dist/store/mongo/index.js +34 -3
- package/dist/store/postgres/index.d.ts +15 -0
- package/dist/store/postgres/index.js +89 -4
- package/dist/store/sqlite/index.d.ts +1 -0
- package/dist/store/sqlite/index.js +32 -2
- package/dist/types.d.ts +16 -0
- package/dist/usages/find.d.ts +29 -0
- package/dist/usages/find.js +115 -0
- package/dist/usages/index.d.ts +2 -0
- package/dist/usages/index.js +1 -0
- package/dist/util/snippet.d.ts +28 -0
- package/dist/util/snippet.js +52 -0
- package/package.json +2 -1
- package/skills/cdb-scan/SKILL.md +72 -0
|
@@ -2,9 +2,10 @@ import { DatabaseSync } from 'node:sqlite';
|
|
|
2
2
|
import { mkdirSync, readFileSync } from 'node:fs';
|
|
3
3
|
import { dirname, resolve } from 'node:path';
|
|
4
4
|
import { fileURLToPath } from 'node:url';
|
|
5
|
-
import { isWholeScope } from '../adapter.js';
|
|
5
|
+
import { foreignNames, isWholeScope } from '../adapter.js';
|
|
6
6
|
import { cosine, packVector, unpackVector } from '../../util/vector.js';
|
|
7
7
|
import { scopeToken } from '../../util/scope.js';
|
|
8
|
+
import { toSnippet } from '../../util/snippet.js';
|
|
8
9
|
import { partitionIds } from '../../util/shortid.js';
|
|
9
10
|
const HERE = dirname(fileURLToPath(import.meta.url));
|
|
10
11
|
/**
|
|
@@ -184,6 +185,13 @@ export class SqliteStore {
|
|
|
184
185
|
lastActive: Number(row['last']),
|
|
185
186
|
}));
|
|
186
187
|
}
|
|
188
|
+
async inventory() {
|
|
189
|
+
const rows = this.db
|
|
190
|
+
.prepare(`SELECT name FROM sqlite_master
|
|
191
|
+
WHERE type IN ('table', 'view') AND name NOT LIKE 'sqlite_%'`)
|
|
192
|
+
.all();
|
|
193
|
+
return foreignNames(rows.map((row) => String(row['name'] ?? '')));
|
|
194
|
+
}
|
|
187
195
|
async searchKeyword(query) {
|
|
188
196
|
// The project constraint goes inside the MATCH expression, not the WHERE
|
|
189
197
|
// clause. Filtering after the match makes FTS5 rank every project's
|
|
@@ -198,6 +206,10 @@ export class SqliteStore {
|
|
|
198
206
|
conditions.push('o.kind = ?');
|
|
199
207
|
params.push(query.kind);
|
|
200
208
|
}
|
|
209
|
+
if (query.tag) {
|
|
210
|
+
conditions.push(TAG_PREDICATE('o.'));
|
|
211
|
+
params.push(query.tag);
|
|
212
|
+
}
|
|
201
213
|
if (query.since !== undefined) {
|
|
202
214
|
conditions.push('o.created_at >= ?');
|
|
203
215
|
params.push(query.since);
|
|
@@ -211,8 +223,13 @@ export class SqliteStore {
|
|
|
211
223
|
// weights (title, body, tags, scope) make a hit in the one-sentence claim
|
|
212
224
|
// outrank the same word buried in a long body; scope carries no weight
|
|
213
225
|
// because it is a filter, not a relevance signal.
|
|
226
|
+
// snippet() over column 1 (body) returns the matched fragment, which is
|
|
227
|
+
// what makes a result choosable without expanding it. Markers are empty
|
|
228
|
+
// because the fragment itself is the signal; single-quoted, since SQLite
|
|
229
|
+
// reads a double-quoted literal as an identifier.
|
|
214
230
|
const rows = this.db
|
|
215
231
|
.prepare(`SELECT o.id, o.kind, o.title, o.project, o.created_at,
|
|
232
|
+
snippet(observations_fts, 1, '', '', '…', 14) AS snippet,
|
|
216
233
|
-bm25(observations_fts, 10.0, 1.0, 5.0, 0.0) AS score
|
|
217
234
|
FROM observations_fts
|
|
218
235
|
JOIN observations o ON o.rowid = observations_fts.rowid
|
|
@@ -311,6 +328,11 @@ function removeWhere(filter) {
|
|
|
311
328
|
params,
|
|
312
329
|
};
|
|
313
330
|
}
|
|
331
|
+
/**
|
|
332
|
+
* Exact membership in the stored JSON array, rather than a LIKE over the raw
|
|
333
|
+
* text, so `api` cannot match `api-docs` and a tag containing `%` is harmless.
|
|
334
|
+
*/
|
|
335
|
+
const TAG_PREDICATE = (prefix) => `EXISTS (SELECT 1 FROM json_each(${prefix}tags) WHERE value = ?)`;
|
|
314
336
|
function appendScope(query, conditions, params, prefix) {
|
|
315
337
|
if (query.project) {
|
|
316
338
|
conditions.push(`${prefix}project = ?`);
|
|
@@ -320,6 +342,10 @@ function appendScope(query, conditions, params, prefix) {
|
|
|
320
342
|
conditions.push(`${prefix}kind = ?`);
|
|
321
343
|
params.push(query.kind);
|
|
322
344
|
}
|
|
345
|
+
if (query.tag) {
|
|
346
|
+
conditions.push(TAG_PREDICATE(prefix));
|
|
347
|
+
params.push(query.tag);
|
|
348
|
+
}
|
|
323
349
|
if (query.since !== undefined) {
|
|
324
350
|
conditions.push(`${prefix}created_at >= ?`);
|
|
325
351
|
params.push(query.since);
|
|
@@ -401,7 +427,7 @@ function toObservation(row) {
|
|
|
401
427
|
return obs;
|
|
402
428
|
}
|
|
403
429
|
function toIndexEntry(row) {
|
|
404
|
-
|
|
430
|
+
const entry = {
|
|
405
431
|
id: row['id'],
|
|
406
432
|
kind: row['kind'],
|
|
407
433
|
title: row['title'],
|
|
@@ -409,4 +435,8 @@ function toIndexEntry(row) {
|
|
|
409
435
|
createdAt: Number(row['created_at']),
|
|
410
436
|
score: Number(row['score'] ?? 0),
|
|
411
437
|
};
|
|
438
|
+
const snippet = toSnippet(row['snippet']);
|
|
439
|
+
if (snippet)
|
|
440
|
+
entry.snippet = snippet;
|
|
441
|
+
return entry;
|
|
412
442
|
}
|
package/dist/types.d.ts
CHANGED
|
@@ -40,11 +40,27 @@ export interface ObservationIndexEntry {
|
|
|
40
40
|
project: string;
|
|
41
41
|
createdAt: number;
|
|
42
42
|
score: number;
|
|
43
|
+
/**
|
|
44
|
+
* A line of the body around the match, so a result can be chosen without
|
|
45
|
+
* being expanded first. Produced by the keyword retriever, which is the only
|
|
46
|
+
* one with query terms to centre on; a row found by vector similarity alone
|
|
47
|
+
* has none.
|
|
48
|
+
*/
|
|
49
|
+
snippet?: string;
|
|
43
50
|
}
|
|
44
51
|
export interface SearchQuery {
|
|
45
52
|
text: string;
|
|
46
53
|
project?: string;
|
|
47
54
|
kind?: ObservationKind;
|
|
55
|
+
/**
|
|
56
|
+
* Narrows to observations touching one repository or top-level directory.
|
|
57
|
+
*
|
|
58
|
+
* A workspace that pools several repositories under one project key gets a
|
|
59
|
+
* memory covering all of them, and "the backend only" is a natural thing to
|
|
60
|
+
* ask that could not be expressed: tags were recorded and ranked, but never
|
|
61
|
+
* filtered on.
|
|
62
|
+
*/
|
|
63
|
+
tag?: string;
|
|
48
64
|
since?: number;
|
|
49
65
|
until?: number;
|
|
50
66
|
limit: number;
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
export interface UsageMatch {
|
|
2
|
+
file: string;
|
|
3
|
+
line: number;
|
|
4
|
+
text: string;
|
|
5
|
+
isDefinition: boolean;
|
|
6
|
+
}
|
|
7
|
+
export interface UsagesResult {
|
|
8
|
+
root: string;
|
|
9
|
+
matches: UsageMatch[];
|
|
10
|
+
total: number;
|
|
11
|
+
truncated: boolean;
|
|
12
|
+
}
|
|
13
|
+
export interface FindUsagesInput {
|
|
14
|
+
symbol: string;
|
|
15
|
+
path?: string;
|
|
16
|
+
regex: boolean;
|
|
17
|
+
context: number;
|
|
18
|
+
limit: number;
|
|
19
|
+
}
|
|
20
|
+
/**
|
|
21
|
+
* Live `git grep`, never a persisted index.
|
|
22
|
+
*
|
|
23
|
+
* A symbol index that drifts from an edit is the same failure shape as every
|
|
24
|
+
* silent-staleness bug this project has already shipped and fixed. This
|
|
25
|
+
* re-derives the answer from the current source on every call, so there is
|
|
26
|
+
* nothing to invalidate.
|
|
27
|
+
*/
|
|
28
|
+
export declare function findUsages(input: FindUsagesInput): UsagesResult;
|
|
29
|
+
export declare function formatUsages(result: UsagesResult): string;
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
import { execFileSync } from 'node:child_process';
|
|
2
|
+
import { resolve } from 'node:path';
|
|
3
|
+
// A hit here means the term is too generic to be a symbol lookup at all; the
|
|
4
|
+
// fix is a narrower query, not a bigger buffer.
|
|
5
|
+
const MAX_BUFFER = 16 * 1024 * 1024;
|
|
6
|
+
/**
|
|
7
|
+
* Live `git grep`, never a persisted index.
|
|
8
|
+
*
|
|
9
|
+
* A symbol index that drifts from an edit is the same failure shape as every
|
|
10
|
+
* silent-staleness bug this project has already shipped and fixed. This
|
|
11
|
+
* re-derives the answer from the current source on every call, so there is
|
|
12
|
+
* nothing to invalidate.
|
|
13
|
+
*/
|
|
14
|
+
export function findUsages(input) {
|
|
15
|
+
const root = repoRootFor(input.path);
|
|
16
|
+
const args = buildArgs(input);
|
|
17
|
+
let raw;
|
|
18
|
+
try {
|
|
19
|
+
raw = execFileSync('git', args, { cwd: root, encoding: 'utf8', maxBuffer: MAX_BUFFER });
|
|
20
|
+
}
|
|
21
|
+
catch (error) {
|
|
22
|
+
const err = error;
|
|
23
|
+
// git grep exits 1 for "ran fine, found nothing" — not an error.
|
|
24
|
+
if (err.status === 1)
|
|
25
|
+
return { root, matches: [], total: 0, truncated: false };
|
|
26
|
+
if (/maxBuffer/i.test(err.message)) {
|
|
27
|
+
throw new Error(`too many matches for "${input.symbol}" to read at once — narrow it ` +
|
|
28
|
+
'(a longer name, --path to a subdirectory, or --regex to anchor it tighter)');
|
|
29
|
+
}
|
|
30
|
+
throw new Error((err.stderr ?? err.message).trim().split('\n')[0]);
|
|
31
|
+
}
|
|
32
|
+
const parsed = parseGrepOutput(raw).map((row) => ({
|
|
33
|
+
...row,
|
|
34
|
+
isDefinition: isDefinitionLike(input.symbol, row.text),
|
|
35
|
+
}));
|
|
36
|
+
return {
|
|
37
|
+
root,
|
|
38
|
+
matches: parsed.slice(0, input.limit),
|
|
39
|
+
total: parsed.length,
|
|
40
|
+
truncated: parsed.length > input.limit,
|
|
41
|
+
};
|
|
42
|
+
}
|
|
43
|
+
/**
|
|
44
|
+
* Deliberately not resolveProject(): that widens to the repository root for
|
|
45
|
+
* MEMORY partitioning, and inside a workspace pooling several sibling repos
|
|
46
|
+
* it can resolve to a directory that is not itself a git working tree, which
|
|
47
|
+
* `git grep` cannot search at all. Delegating to git's own discovery keeps
|
|
48
|
+
* this in sync with whatever repo git itself would act on (worktrees,
|
|
49
|
+
* submodules, symlinks included) without a second implementation of the walk.
|
|
50
|
+
*/
|
|
51
|
+
function repoRootFor(path) {
|
|
52
|
+
const start = resolve(path ?? process.cwd());
|
|
53
|
+
try {
|
|
54
|
+
return execFileSync('git', ['-C', start, 'rev-parse', '--show-toplevel'], {
|
|
55
|
+
encoding: 'utf8',
|
|
56
|
+
}).trim();
|
|
57
|
+
}
|
|
58
|
+
catch (error) {
|
|
59
|
+
const stderr = error.stderr?.trim();
|
|
60
|
+
throw new Error(`${start} is not inside a git working tree${stderr ? ` (${stderr})` : ''}`);
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
function buildArgs({ symbol, regex, context }) {
|
|
64
|
+
// -I: skip binary files — a binary hit otherwise prints a headerless
|
|
65
|
+
// "Binary file X matches" line that corrupts the -z parse below.
|
|
66
|
+
// --untracked: a brand-new file the agent just created and has not `git
|
|
67
|
+
// add`ed yet is exactly the blast-radius case this tool exists for; without
|
|
68
|
+
// this flag it is silently invisible. Still respects .gitignore.
|
|
69
|
+
const args = ['grep', '-n', '-z', '-I', '--untracked'];
|
|
70
|
+
if (context > 0)
|
|
71
|
+
args.push(`-B${context}`, `-A${context}`);
|
|
72
|
+
// Word-regexp only in literal mode: a regex author already controls their
|
|
73
|
+
// own boundaries, so imposing one on top would be a surprise, not a safety net.
|
|
74
|
+
args.push(...(regex ? ['--extended-regexp'] : ['--fixed-strings', '--word-regexp']));
|
|
75
|
+
args.push('-e', symbol);
|
|
76
|
+
return args;
|
|
77
|
+
}
|
|
78
|
+
/** `-z` NUL-delimits path\0line\0content per record; a stray line with no
|
|
79
|
+
* NUL (a `--` context divider, a binary-match notice) is simply dropped. */
|
|
80
|
+
function parseGrepOutput(raw) {
|
|
81
|
+
const rows = [];
|
|
82
|
+
for (const record of raw.split('\n')) {
|
|
83
|
+
if (!record.includes('\0'))
|
|
84
|
+
continue;
|
|
85
|
+
const [file, lineStr, ...rest] = record.split('\0');
|
|
86
|
+
const line = Number(lineStr);
|
|
87
|
+
if (!file || !Number.isFinite(line))
|
|
88
|
+
continue;
|
|
89
|
+
rows.push({ file, line, text: rest.join('\0') });
|
|
90
|
+
}
|
|
91
|
+
return rows;
|
|
92
|
+
}
|
|
93
|
+
/**
|
|
94
|
+
* Cheap, best-effort "this looks like the declaration" marker. Unlike
|
|
95
|
+
* classifyTurn's `because` regression, this never hides or filters a line —
|
|
96
|
+
* it only annotates one already-shown line, so a false positive costs a
|
|
97
|
+
* wrong label, not a silently misfiled result.
|
|
98
|
+
*/
|
|
99
|
+
function isDefinitionLike(symbol, text) {
|
|
100
|
+
const s = symbol.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
|
|
101
|
+
return new RegExp(`\\b(function\\*?\\s+${s}\\b` +
|
|
102
|
+
`|class\\s+${s}\\b` +
|
|
103
|
+
`|(?:interface|type|enum)\\s+${s}\\b` +
|
|
104
|
+
`|(?:export\\s+)?(?:const|let|var)\\s+${s}\\s*[:=]` +
|
|
105
|
+
`|export\\s*\\{[^}]*\\b${s}\\b)`).test(text);
|
|
106
|
+
}
|
|
107
|
+
export function formatUsages(result) {
|
|
108
|
+
if (result.matches.length === 0)
|
|
109
|
+
return `No usages of that symbol found under ${result.root}.`;
|
|
110
|
+
const rows = result.matches.map((m) => `${m.file}:${m.line}${m.isDefinition ? ' [definition?]' : ''} ${m.text.trim()}`);
|
|
111
|
+
const header = result.truncated
|
|
112
|
+
? `showing ${result.matches.length} of ${result.total}+ match(es) (raise \`limit\` or narrow \`symbol\`):`
|
|
113
|
+
: `${result.total} match(es):`;
|
|
114
|
+
return `${header}\n${rows.join('\n')}`;
|
|
115
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export { findUsages, formatUsages } from './find.js';
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Shaping for the two places a body is shown in part rather than in full.
|
|
3
|
+
*
|
|
4
|
+
* Layer 1 was built on the assumption that a title tells you which row holds
|
|
5
|
+
* the answer. It often does not — "Committed as 30daa92" is a true report of an
|
|
6
|
+
* outcome and says nothing about whether to expand it — so a search returned
|
|
7
|
+
* fifteen rows that all looked alike and the only way to choose was to guess.
|
|
8
|
+
* A snippet costs about sixty characters and saves a whole body per wrong
|
|
9
|
+
* guess, which is the trade the terse index was making in the wrong direction.
|
|
10
|
+
*/
|
|
11
|
+
/**
|
|
12
|
+
* One line, whitespace collapsed, clipped at a word boundary.
|
|
13
|
+
*
|
|
14
|
+
* Bodies carry newlines, markdown tables and code, none of which survive being
|
|
15
|
+
* shown on one line of an index; and the search engines wrap matches in their
|
|
16
|
+
* own markers, which are noise once the fragment is already the point.
|
|
17
|
+
*/
|
|
18
|
+
export declare function toSnippet(text: unknown, max?: number): string | undefined;
|
|
19
|
+
/**
|
|
20
|
+
* Bounds a full body at layer 3.
|
|
21
|
+
*
|
|
22
|
+
* The cost argument that made the index terse was never applied one layer down,
|
|
23
|
+
* where a single call may ask for twenty-five bodies at once — so the multiplier
|
|
24
|
+
* is far worse there than in the index it was written for. The remainder is
|
|
25
|
+
* counted rather than dropped silently, because a reader who needs the rest has
|
|
26
|
+
* to know it exists.
|
|
27
|
+
*/
|
|
28
|
+
export declare function clipBody(body: string, max: number): string;
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Shaping for the two places a body is shown in part rather than in full.
|
|
3
|
+
*
|
|
4
|
+
* Layer 1 was built on the assumption that a title tells you which row holds
|
|
5
|
+
* the answer. It often does not — "Committed as 30daa92" is a true report of an
|
|
6
|
+
* outcome and says nothing about whether to expand it — so a search returned
|
|
7
|
+
* fifteen rows that all looked alike and the only way to choose was to guess.
|
|
8
|
+
* A snippet costs about sixty characters and saves a whole body per wrong
|
|
9
|
+
* guess, which is the trade the terse index was making in the wrong direction.
|
|
10
|
+
*/
|
|
11
|
+
const SNIPPET_MAX = 110;
|
|
12
|
+
/**
|
|
13
|
+
* One line, whitespace collapsed, clipped at a word boundary.
|
|
14
|
+
*
|
|
15
|
+
* Bodies carry newlines, markdown tables and code, none of which survive being
|
|
16
|
+
* shown on one line of an index; and the search engines wrap matches in their
|
|
17
|
+
* own markers, which are noise once the fragment is already the point.
|
|
18
|
+
*/
|
|
19
|
+
export function toSnippet(text, max = SNIPPET_MAX) {
|
|
20
|
+
if (typeof text !== 'string')
|
|
21
|
+
return undefined;
|
|
22
|
+
// Backticks, pipes and asterisks are markup and only ever noise on one line.
|
|
23
|
+
// Underscores and hashes are left alone: they are far more often part of an
|
|
24
|
+
// identifier than of emphasis, and stripping them turned
|
|
25
|
+
// `aggregation_cursor.js` into two words that match nothing.
|
|
26
|
+
const flat = text
|
|
27
|
+
.replace(/<\/?b>/g, '')
|
|
28
|
+
.replace(/[|`*]+/g, ' ')
|
|
29
|
+
.replace(/\s+/g, ' ')
|
|
30
|
+
.trim();
|
|
31
|
+
if (flat.length === 0)
|
|
32
|
+
return undefined;
|
|
33
|
+
if (flat.length <= max)
|
|
34
|
+
return flat;
|
|
35
|
+
const cut = flat.slice(0, max);
|
|
36
|
+
const word = cut.lastIndexOf(' ');
|
|
37
|
+
return `${cut.slice(0, word > max * 0.6 ? word : max)}…`;
|
|
38
|
+
}
|
|
39
|
+
/**
|
|
40
|
+
* Bounds a full body at layer 3.
|
|
41
|
+
*
|
|
42
|
+
* The cost argument that made the index terse was never applied one layer down,
|
|
43
|
+
* where a single call may ask for twenty-five bodies at once — so the multiplier
|
|
44
|
+
* is far worse there than in the index it was written for. The remainder is
|
|
45
|
+
* counted rather than dropped silently, because a reader who needs the rest has
|
|
46
|
+
* to know it exists.
|
|
47
|
+
*/
|
|
48
|
+
export function clipBody(body, max) {
|
|
49
|
+
if (body.length <= max)
|
|
50
|
+
return body;
|
|
51
|
+
return `${body.slice(0, max)}\n… ${body.length - max} more characters (raise \`chars\` to read them)`;
|
|
52
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "claude-db",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.4.0",
|
|
4
4
|
"description": "Persistent memory for Claude Code. Captures why decisions were made, not just which files changed. Bring your own database: SQLite, MongoDB or Postgres. No cloud, no subscription.",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"type": "module",
|
|
@@ -16,6 +16,7 @@
|
|
|
16
16
|
},
|
|
17
17
|
"files": [
|
|
18
18
|
"dist",
|
|
19
|
+
"skills",
|
|
19
20
|
"README.md",
|
|
20
21
|
"LICENSE"
|
|
21
22
|
],
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: cdb-scan
|
|
3
|
+
description: Survey this codebase once and store a profile of it in project memory — stack, layout, conventions, workflows. Re-run any time to refresh it in place. Use when memory is newly installed on an existing project, or when the project has changed enough that the stored profile is stale.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Survey this project into memory
|
|
7
|
+
|
|
8
|
+
Everything else in claude-db's memory is testimony: it records what happened,
|
|
9
|
+
turn by turn, as it happened. A fresh install knows none of that, and stays
|
|
10
|
+
useless for weeks while it fills up.
|
|
11
|
+
|
|
12
|
+
This fills the gap from the one source available on day one — the code itself.
|
|
13
|
+
What you write here is **your reading of the codebase, not a record of events**,
|
|
14
|
+
so it is tagged `inferred` and must never be phrased as history.
|
|
15
|
+
|
|
16
|
+
## How to run it
|
|
17
|
+
|
|
18
|
+
Work through the sections below in order. For each one, look at the actual
|
|
19
|
+
files, then call the `remember` MCP tool once with the given `key`.
|
|
20
|
+
|
|
21
|
+
`key` is what makes this re-runnable: writing the same key again replaces that
|
|
22
|
+
note rather than adding a second copy. Use these exact keys, and always pass
|
|
23
|
+
`tags: ["inferred"]` and `kind: "context"`.
|
|
24
|
+
|
|
25
|
+
Before you start, call `search` for `profile` in this project. If notes already
|
|
26
|
+
exist, read them first and update what changed rather than restating it — a
|
|
27
|
+
second run should be an edit, not a rewrite.
|
|
28
|
+
|
|
29
|
+
### 1. `profile:stack`
|
|
30
|
+
|
|
31
|
+
Languages, runtime and version floors, frameworks, package manager, database,
|
|
32
|
+
test runner, build tool. Read the manifest (`package.json`, `pyproject.toml`,
|
|
33
|
+
`go.mod`, `Cargo.toml`) and the lockfile rather than guessing. Name versions
|
|
34
|
+
where a version constrains what can be written.
|
|
35
|
+
|
|
36
|
+
### 2. `profile:layout`
|
|
37
|
+
|
|
38
|
+
The directory map, one line each, and what lives where. Include the entry
|
|
39
|
+
points: the binary, the server, the main export. Skip anything generated.
|
|
40
|
+
|
|
41
|
+
### 3. `profile:conventions`
|
|
42
|
+
|
|
43
|
+
How this codebase is written, taken from the code and not from a style guide:
|
|
44
|
+
module system, import style, error handling, naming, comment density, how
|
|
45
|
+
tests are structured. Note where the project deviates from the language default,
|
|
46
|
+
since that is what someone would otherwise get wrong.
|
|
47
|
+
|
|
48
|
+
### 4. `profile:workflows`
|
|
49
|
+
|
|
50
|
+
The commands that matter — install, build, test, lint, run, release — and
|
|
51
|
+
anything non-obvious about running them: a required service, an environment
|
|
52
|
+
variable, a step that must come first. Take them from the manifest scripts and
|
|
53
|
+
CI config, not from the README's aspirations.
|
|
54
|
+
|
|
55
|
+
### 5. `profile:architecture`
|
|
56
|
+
|
|
57
|
+
Only the parts a newcomer could not infer from the layout: the main
|
|
58
|
+
abstractions and how a request or a command actually flows through them. Two
|
|
59
|
+
paragraphs at most. If the codebase is small enough that the layout says it
|
|
60
|
+
all, skip this section rather than padding it.
|
|
61
|
+
|
|
62
|
+
## Rules
|
|
63
|
+
|
|
64
|
+
- **One `remember` call per section.** Five notes, five stable keys.
|
|
65
|
+
- **Write claims, not headings.** "Storage is one `MemoryStore` interface with
|
|
66
|
+
three adapters, selected by URI scheme" — not "Storage architecture".
|
|
67
|
+
- **Say what you verified.** If something was not read, leave it out. An
|
|
68
|
+
inferred profile that is confidently wrong is worse than a short one.
|
|
69
|
+
- **Never restate `CLAUDE.md`.** That file is already in the system prompt on
|
|
70
|
+
every turn. Memory is for what is not.
|
|
71
|
+
- **Do not record secrets, credentials or personal data**, even if the code
|
|
72
|
+
contains them.
|