@roackb2/heddle 0.0.28 → 0.0.29

package/dist/src/core/memory/catalog.js

@@ -0,0 +1,230 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { buildMemoryDomainSystemContext } from './domain-prompt.js';
+export const DEFAULT_MEMORY_ROOT_CATALOG_MAX_BYTES = 12 * 1024;
+export const DEFAULT_MEMORY_ROOT_CATALOG_TARGET_BYTES = 8 * 1024;
+export const DEFAULT_MEMORY_FOLDER_CATALOG_MAX_BYTES = 8 * 1024;
+export const DEFAULT_MEMORY_FOLDER_CATALOG_TARGET_BYTES = 5 * 1024;
+export const DEFAULT_MEMORY_CATEGORIES = [
+    {
+        path: 'current-state',
+        title: 'Current State',
+        purpose: 'Fresh-session summary, active workstreams, blockers, and recent verified changes.',
+        readWhen: 'Start here for non-trivial work or when the user asks what is happening now.',
+    },
+    {
+        path: 'workflows',
+        title: 'Workflows',
+        purpose: 'Procedures for planning, implementation, review, release, incident, and support work.',
+        readWhen: 'Use when the task is process-heavy or the user asks you to follow an established workflow.',
+    },
+    {
+        path: 'preferences',
+        title: 'Preferences',
+        purpose: 'User or team preferences that should shape communication, code style, risk tolerance, and review behavior.',
+        readWhen: 'Use before making broad implementation, design, communication, or review choices.',
+    },
+    {
+        path: 'domain',
+        title: 'Domain',
+        purpose: 'Durable project, product, architecture, service, data, or business-domain knowledge.',
+        readWhen: 'Use before answering architecture questions or changing unfamiliar project behavior.',
+    },
+    {
+        path: 'operations',
+        title: 'Operations',
+        purpose: 'Commands, environments, deployment/release surfaces, operational status, credentials caveats, and safety notes.',
+        readWhen: 'Use before running verification, deployment, migration, incident, or environment-sensitive work.',
+    },
+    {
+        path: 'relationships',
+        title: 'Relationships',
+        purpose: 'People, teams, systems, projects, ownership, dependencies, escalation paths, and schedules.',
+        readWhen: 'Use when work depends on ownership, coordination, external systems, stakeholders, or timing.',
+    },
+    {
+        path: 'history',
+        title: 'History',
+        purpose: 'Completed decisions, incidents, investigations, migrations, and older context that explains current constraints.',
+        readWhen: 'Use when current behavior has historical causes or the task resembles a past incident or decision.',
+    },
+];
+export function bootstrapMemoryWorkspace(options) {
+    const memoryRoot = resolve(options.memoryRoot);
+    const createdPaths = [];
+    mkdirSync(memoryRoot, { recursive: true });
+    writeIfMissing(join(memoryRoot, 'README.md'), createRootCatalogTemplate(), createdPaths, memoryRoot);
+    for (const category of DEFAULT_MEMORY_CATEGORIES) {
+        const categoryRoot = join(memoryRoot, category.path);
+        mkdirSync(categoryRoot, { recursive: true });
+        writeIfMissing(join(categoryRoot, 'README.md'), createFolderCatalogTemplate(category), createdPaths, memoryRoot);
+    }
+    mkdirSync(join(memoryRoot, '_maintenance'), { recursive: true });
+    writeIfMissing(join(memoryRoot, '_maintenance', 'runs.jsonl'), '', createdPaths, memoryRoot);
+    return { memoryRoot, createdPaths };
+}
+export function loadMemoryRootCatalog(options) {
+    const memoryRoot = resolve(options.memoryRoot);
+    const maxBytes = options.maxBytes ?? DEFAULT_MEMORY_ROOT_CATALOG_MAX_BYTES;
+    const catalogPath = join(memoryRoot, 'README.md');
+    if (!existsSync(catalogPath)) {
+        const content = [
+            'No workspace memory catalog exists yet.',
+            '',
+            `Expected root catalog: ${catalogPath}`,
+            '',
+            'Memory remains available through list/read/search tools when notes exist, but startup recall is not initialized.',
+            'Initialize a cataloged memory workspace before relying on durable recall.',
+        ].join('\n');
+        return {
+            memoryRoot,
+            catalogPath,
+            exists: false,
+            content,
+            truncated: false,
+            originalBytes: Buffer.byteLength(content, 'utf8'),
+            maxBytes,
+        };
+    }
+    const original = readFileSync(catalogPath, 'utf8').trim();
+    const originalBytes = Buffer.byteLength(original, 'utf8');
+    const truncatedContent = truncateUtf8(original, maxBytes);
+    const truncated = originalBytes > Buffer.byteLength(truncatedContent, 'utf8');
+    const content = truncated ?
+        [
+            truncatedContent,
+            '',
+            `[Memory catalog truncated to ${maxBytes} bytes from ${originalBytes} bytes. Use read_memory_note on README.md for the full catalog.]`,
+        ].join('\n')
+        : original;
+    return {
+        memoryRoot,
+        catalogPath,
+        exists: true,
+        content,
+        truncated,
+        originalBytes,
+        maxBytes,
+    };
+}
+export function formatMemoryCatalogSystemContext(catalog) {
+    const header = catalog.exists ? '## Workspace Memory Catalog' : '## Workspace Memory Catalog Missing';
+    return [
+        header,
+        '',
+        `Source: ${catalog.catalogPath}`,
+        '',
+        catalog.content,
+        '',
+        'Startup memory policy: this is the only memory document loaded automatically. Use memory tools to read relevant folder catalogs or notes before relying on deeper memory.',
+    ].join('\n');
+}
+export function appendMemoryCatalogSystemContext(options) {
+    const catalog = loadMemoryRootCatalog({ memoryRoot: options.memoryRoot, maxBytes: options.maxBytes });
+    const memoryContext = formatMemoryCatalogSystemContext(catalog);
+    const domainContext = buildMemoryDomainSystemContext();
+    const context = `${domainContext}\n\n${memoryContext}`;
+    return options.systemContext ? `${options.systemContext}\n\n${context}` : context;
+}
+export function validateMemoryCatalogShape(options) {
+    const memoryRoot = resolve(options.memoryRoot);
+    const requiredPaths = [
+        'README.md',
+        ...DEFAULT_MEMORY_CATEGORIES.map((category) => join(category.path, 'README.md')),
+    ];
+    const missing = requiredPaths.filter((relativePath) => !existsSync(join(memoryRoot, relativePath)));
+    return {
+        ok: missing.length === 0,
+        memoryRoot,
+        missing,
+    };
+}
+function writeIfMissing(path, content, createdPaths, memoryRoot) {
+    if (existsSync(path)) {
+        return;
+    }
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, content, 'utf8');
+    createdPaths.push(toMemoryRelativePath(memoryRoot, path));
+}
+function createRootCatalogTemplate() {
+    return [
+        '# Workspace Memory',
+        '',
+        'Purpose: durable workspace knowledge that helps future agents become operational quickly.',
+        '',
+        '## Authority And Freshness',
+        '',
+        '- Live workspace evidence wins over memory when they disagree.',
+        '- Current-state notes with recent verification are stronger than older focused notes.',
+        '- Historical notes explain decisions and incidents but may be stale.',
+        '- Important stale, disputed, or superseded facts should be marked rather than silently removed.',
+        '',
+        '## Fast Reading Path',
+        '',
+        '- New non-trivial task: read `current-state/README.md`, then the category that matches the task.',
+        '- Coding or architecture task: read `domain/README.md`, `operations/README.md`, and relevant preferences.',
+        '- Workflow, release, PR, or incident task: read `workflows/README.md`, `operations/README.md`, and relevant history.',
+        '- Coordination-heavy task: read `relationships/README.md`.',
+        '',
+        '## Category Index',
+        '',
+        ...DEFAULT_MEMORY_CATEGORIES.map((category) => `- [${category.title}](${category.path}/README.md): ${category.purpose}`),
+        '',
+        '## High-Value Notes',
+        '',
+        '- Add links here when notes become important enough for every fresh agent to notice.',
+        '',
+        '## Stale Or Disputed Notes',
+        '',
+        '- Add links here when a note should be treated with caution.',
+        '',
+        '## Maintenance Instructions',
+        '',
+        '- Keep this catalog short and navigable.',
+        '- Every folder that contains memory notes needs its own `README.md` catalog.',
+        '- Every durable note should be discoverable through this catalog or a folder catalog.',
+        '- Prefer updating existing notes over scattering small one-off notes.',
+        '- Do not store secrets.',
+        '',
+    ].join('\n');
+}
+function createFolderCatalogTemplate(category) {
+    return [
+        `# ${category.title}`,
+        '',
+        `Purpose: ${category.purpose}`,
+        '',
+        `When to read: ${category.readWhen}`,
+        '',
+        '## Notes Index',
+        '',
+        '- Add note links here as this folder grows.',
+        '',
+        '## Related Folders',
+        '',
+        '- `../README.md`: root memory catalog.',
+        '',
+        '## Maintenance Rules',
+        '',
+        '- Keep this catalog short enough to scan quickly.',
+        '- Add notes only when they preserve durable context for future work.',
+        '- Update this catalog whenever adding, renaming, or retiring notes in this folder.',
+        '- Mark stale, disputed, or superseded knowledge explicitly.',
+        '',
+    ].join('\n');
+}
+function truncateUtf8(value, maxBytes) {
+    if (maxBytes <= 0) {
+        return '';
+    }
+    const bytes = Buffer.from(value, 'utf8');
+    if (bytes.length <= maxBytes) {
+        return value;
+    }
+    return bytes.subarray(0, maxBytes).toString('utf8').replace(/\uFFFD+$/u, '').trimEnd();
+}
+function toMemoryRelativePath(memoryRoot, path) {
+    return path.slice(memoryRoot.length).replace(/^\/+/, '') || '.';
+}
+//# sourceMappingURL=catalog.js.map

package/dist/src/core/memory/catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../../../../src/core/memory/catalog.ts"],"names":[],"mappings":"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"}

package/dist/src/core/memory/domain-prompt.d.ts

@@ -0,0 +1,2 @@
+export declare function buildMemoryDomainSystemContext(): string;
+//# sourceMappingURL=domain-prompt.d.ts.map

package/dist/src/core/memory/domain-prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"domain-prompt.d.ts","sourceRoot":"","sources":["../../../../src/core/memory/domain-prompt.ts"],"names":[],"mappings":"AAAA,wBAAgB,8BAA8B,IAAI,MAAM,CAiCvD"}

package/dist/src/core/memory/domain-prompt.js

@@ -0,0 +1,35 @@
+export function buildMemoryDomainSystemContext() {
+    return [
+        '## Heddle-Managed Memory Domain',
+        '',
+        'Heddle-managed memory is the durable recall substrate for the agent. It is different from ordinary repository documentation.',
+        '',
+        '### Knowledge Surfaces',
+        '',
+        '- Repository docs such as README files, AGENTS.md, or docs/ are project-authored evidence. Use them for current product, code, and user-facing documentation facts.',
+        '- Heddle-managed memory under .heddle/memory is agent-maintained durable context. Use it for preferences, workflows, current-state handoff, operational conventions, relationships, history, and not-obvious knowledge that helps future sessions avoid rediscovery.',
+        '- Live workspace evidence wins when implementation facts conflict with memory. Memory is strongest for user/team preferences, recurring workflows, historical context, and operational knowledge that may not be obvious from code.',
+        '',
+        '### Retrieval Model',
+        '',
+        '- For preference-shaped, workflow-shaped, planning-style, ticket/format, review-style, coordination, or recurring operational questions, consult Heddle-managed memory before broad repository search.',
+        '- Follow the catalog path: read the root memory catalog, then the relevant folder README catalog, then focused notes listed there.',
+        '- Use search_memory_notes when the likely folder is unclear. Use list_memory_notes and read_memory_note when the catalog already points to a likely folder or note.',
+        '- Do not grep ordinary repo files first for durable preferences or workflow conventions unless memory has no relevant path or live repository evidence is needed.',
+        '',
+        '### Maintenance Model',
+        '',
+        '- Preserve the discovery path. Every durable memory note must be discoverable from the root README.md or a folder README.md.',
+        '- Prefer updating an existing cataloged note over scattering many small notes.',
+        '- Keep folder README.md files as indexes, not long-form dumps.',
+        '- Do not store secrets, speculative guesses, one-turn plans, or temporary command output.',
+        '',
+        '### Checkpoint Model',
+        '',
+        '- Before the final answer, run a quick memory checkpoint when memory_checkpoint is available.',
+        '- Record durable candidates when the user states a future preference/workflow/format or the turn uncovers stable reusable workspace knowledge.',
+        '- Skip one-off task details, duplicate facts, temporary plans, speculative guesses, and information that should remain only in the current transcript.',
+        '',
+    ].join('\n');
+}
+//# sourceMappingURL=domain-prompt.js.map

package/dist/src/core/memory/domain-prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"domain-prompt.js","sourceRoot":"","sources":["../../../../src/core/memory/domain-prompt.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,8BAA8B;IAC5C,OAAO;QACL,iCAAiC;QACjC,EAAE;QACF,8HAA8H;QAC9H,EAAE;QACF,wBAAwB;QACxB,EAAE;QACF,qKAAqK;QACrK,sQAAsQ;QACtQ,qOAAqO;QACrO,EAAE;QACF,qBAAqB;QACrB,EAAE;QACF,wMAAwM;QACxM,oIAAoI;QACpI,qKAAqK;QACrK,mKAAmK;QACnK,EAAE;QACF,uBAAuB;QACvB,EAAE;QACF,8HAA8H;QAC9H,gFAAgF;QAChF,gEAAgE;QAChE,2FAA2F;QAC3F,EAAE;QACF,sBAAsB;QACtB,EAAE;QACF,+FAA+F;QAC/F,gJAAgJ;QAChJ,wJAAwJ;QACxJ,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}

package/dist/src/core/memory/maintainer-tools.d.ts

@@ -0,0 +1,5 @@
+import type { ToolDefinition } from '../types.js';
+export declare function createMemoryMaintainerTools(options: {
+    memoryRoot: string;
+}): ToolDefinition[];
+//# sourceMappingURL=maintainer-tools.d.ts.map

package/dist/src/core/memory/maintainer-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"maintainer-tools.d.ts","sourceRoot":"","sources":["../../../../src/core/memory/maintainer-tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAQlD,wBAAgB,2BAA2B,CAAC,OAAO,EAAE;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,GAAG,cAAc,EAAE,CAO7F"}

package/dist/src/core/memory/maintainer-tools.js

@@ -0,0 +1,10 @@
+import { createEditMemoryNoteTool, createListMemoryNotesTool, createReadMemoryNoteTool, createSearchMemoryNotesTool, } from '../tools/memory-notes.js';
+export function createMemoryMaintainerTools(options) {
+    return [
+        createListMemoryNotesTool({ memoryRoot: options.memoryRoot }),
+        createReadMemoryNoteTool({ memoryRoot: options.memoryRoot }),
+        createSearchMemoryNotesTool({ memoryRoot: options.memoryRoot }),
+        createEditMemoryNoteTool({ memoryRoot: options.memoryRoot }),
+    ];
+}
+//# sourceMappingURL=maintainer-tools.js.map

package/dist/src/core/memory/maintainer-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"maintainer-tools.js","sourceRoot":"","sources":["../../../../src/core/memory/maintainer-tools.ts"],"names":[],"mappings":"AACA,OAAO,EACL,wBAAwB,EACxB,yBAAyB,EACzB,wBAAwB,EACxB,2BAA2B,GAC5B,MAAM,0BAA0B,CAAC;AAElC,MAAM,UAAU,2BAA2B,CAAC,OAA+B;IACzE,OAAO;QACL,yBAAyB,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE,CAAC;QAC7D,wBAAwB,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE,CAAC;QAC5D,2BAA2B,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE,CAAC;QAC/D,wBAAwB,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE,CAAC;KAC7D,CAAC;AACJ,CAAC"}

package/dist/src/core/memory/maintainer.d.ts

@@ -0,0 +1,45 @@
+import type { LlmAdapter } from '../llm/types.js';
+import type { RunResult } from '../types.js';
+export type KnowledgeCandidate = {
+    id: string;
+    recordedAt: string;
+    status: 'pending';
+    summary: string;
+    evidence?: string[];
+    categoryHint?: string;
+    importance?: 'low' | 'medium' | 'high';
+    confidence?: 'user-stated' | 'tool-verified' | 'inferred' | 'historical';
+    sourceRefs?: string[];
+};
+export type KnowledgeMaintenanceRunRecord = {
+    id: string;
+    startedAt: string;
+    finishedAt: string;
+    source: string;
+    outcome: RunResult['outcome'] | 'skipped';
+    summary: string;
+    candidateIds: string[];
+    processedCandidateIds: string[];
+    failedCandidateIds: string[];
+    catalogValid: boolean;
+    catalogMissing: string[];
+};
+export type RunKnowledgeMaintenanceOptions = {
+    memoryRoot: string;
+    observations: KnowledgeCandidate[];
+    llm: LlmAdapter;
+    source: string;
+    maxSteps?: number;
+    now?: () => Date;
+    nextRunId?: () => string;
+};
+export type RunKnowledgeMaintenanceResult = {
+    run: KnowledgeMaintenanceRunRecord;
+    result?: RunResult;
+};
+export declare function readPendingKnowledgeCandidates(options: {
+    memoryRoot: string;
+}): Promise<KnowledgeCandidate[]>;
+export declare function runKnowledgeMaintenance(options: RunKnowledgeMaintenanceOptions): Promise<RunKnowledgeMaintenanceResult>;
+export declare function runKnowledgeMaintenanceForBacklog(options: Omit<RunKnowledgeMaintenanceOptions, 'observations'>): Promise<RunKnowledgeMaintenanceResult>;
+//# sourceMappingURL=maintainer.d.ts.map

package/dist/src/core/memory/maintainer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"maintainer.d.ts","sourceRoot":"","sources":["../../../../src/core/memory/maintainer.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAM7C,MAAM,MAAM,kBAAkB,GAAG;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,SAAS,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IACvC,UAAU,CAAC,EAAE,aAAa,GAAG,eAAe,GAAG,UAAU,GAAG,YAAY,CAAC;IACzE,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,6BAA6B,GAAG;IAC1C,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,SAAS,CAAC,SAAS,CAAC,GAAG,SAAS,CAAC;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,qBAAqB,EAAE,MAAM,EAAE,CAAC;IAChC,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,YAAY,EAAE,OAAO,CAAC;IACtB,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,8BAA8B,GAAG;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,kBAAkB,EAAE,CAAC;IACnC,GAAG,EAAE,UAAU,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,MAAM,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,6BAA6B,GAAG;IAC1C,GAAG,EAAE,6BAA6B,CAAC;IACnC,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB,CAAC;AAEF,wBAAsB,8BAA8B,CAAC,OAAO,EAAE;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAwBnH;AAED,wBAAsB,uBAAuB,CAAC,OAAO,EAAE,8BAA8B,GAAG,OAAO,CAAC,6BAA6B,CAAC,CAoE7H;AAWD,wBAAsB,iCAAiC,CAAC,OAAO,EAAE,IAAI,CAAC,8BAA8B,EAAE,cAAc,CAAC,GAAG,OAAO,CAAC,6BAA6B,CAAC,CAG7J"}

package/dist/src/core/memory/maintainer.js

@@ -0,0 +1,204 @@
+import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { runAgent } from '../agent/run-agent.js';
+import { createLogger } from '../utils/logger.js';
+import { bootstrapMemoryWorkspace, loadMemoryRootCatalog, validateMemoryCatalogShape } from './catalog.js';
+import { createMemoryMaintainerTools } from './maintainer-tools.js';
+export async function readPendingKnowledgeCandidates(options) {
+    const memoryRoot = resolve(options.memoryRoot);
+    const candidatesPath = join(memoryRoot, '_maintenance', 'candidates.jsonl');
+    const lines = await readJsonlLines(candidatesPath);
+    const processed = new Set();
+    const pending = [];
+    for (const line of lines) {
+        const parsed = parseJsonObject(line);
+        if (!parsed) {
+            continue;
+        }
+        if (parsed.kind === 'candidate_status' && typeof parsed.candidateId === 'string' && parsed.status === 'processed') {
+            processed.add(parsed.candidateId);
+            continue;
+        }
+        if (isKnowledgeCandidate(parsed)) {
+            pending.push(parsed);
+        }
+    }
+    return pending.filter((candidate) => !processed.has(candidate.id));
+}
+export async function runKnowledgeMaintenance(options) {
+    const memoryRoot = resolve(options.memoryRoot);
+    bootstrapMemoryWorkspace({ memoryRoot });
+    const now = options.now ?? (() => new Date());
+    const startedAt = now();
+    const runId = options.nextRunId?.() ?? `memory-run-${startedAt.getTime()}`;
+    const candidateIds = options.observations.map((candidate) => candidate.id);
+    const skippedCandidateIds = options.observations
+        .filter((candidate) => !isMaintainerCandidateAllowed(candidate))
+        .map((candidate) => candidate.id);
+    const observations = options.observations.filter(isMaintainerCandidateAllowed);
+    if (observations.length === 0) {
+        const validation = validateMemoryCatalogShape({ memoryRoot });
+        const summary = candidateIds.length === 0 ? 'No pending knowledge candidates.'
+            : `Skipped ${candidateIds.length} low-value, duplicate, or secret-like memory candidate(s).`;
+        const run = {
+            id: runId,
+            startedAt: startedAt.toISOString(),
+            finishedAt: now().toISOString(),
+            source: options.source,
+            outcome: 'skipped',
+            summary,
+            candidateIds,
+            processedCandidateIds: [],
+            failedCandidateIds: skippedCandidateIds,
+            catalogValid: validation.ok,
+            catalogMissing: validation.missing,
+        };
+        await appendMaintenanceRun(memoryRoot, run);
+        return { run };
+    }
+    const rootCatalog = loadMemoryRootCatalog({ memoryRoot }).content;
+    const goal = buildMaintenanceGoal(observations);
+    const systemContext = buildMaintainerSystemContext(rootCatalog);
+    const result = await runAgent({
+        goal,
+        llm: options.llm,
+        tools: createMemoryMaintainerTools({ memoryRoot }),
+        maxSteps: options.maxSteps ?? 40,
+        logger: createLogger({ console: false, level: 'silent' }),
+        systemContext,
+    });
+    const validation = validateMemoryCatalogShape({ memoryRoot });
+    const processedCandidateIds = result.outcome === 'done' ? observations.map((candidate) => candidate.id) : [];
+    const failedCandidateIds = result.outcome === 'done' ? skippedCandidateIds : candidateIds;
+    const run = {
+        id: runId,
+        startedAt: startedAt.toISOString(),
+        finishedAt: now().toISOString(),
+        source: options.source,
+        outcome: result.outcome,
+        summary: result.summary,
+        candidateIds,
+        processedCandidateIds,
+        failedCandidateIds,
+        catalogValid: validation.ok,
+        catalogMissing: validation.missing,
+    };
+    await appendMaintenanceRun(memoryRoot, run);
+    if (processedCandidateIds.length > 0) {
+        await appendCandidateStatusEvents(memoryRoot, processedCandidateIds, run.id, now);
+    }
+    return { run, result };
+}
+function isMaintainerCandidateAllowed(candidate) {
+    const text = [
+        candidate.summary,
+        ...(candidate.evidence ?? []),
+        ...(candidate.sourceRefs ?? []),
+    ].join('\n');
+    return !containsSecretLikeText(text);
+}
+export async function runKnowledgeMaintenanceForBacklog(options) {
+    const observations = await readPendingKnowledgeCandidates({ memoryRoot: options.memoryRoot });
+    return await runKnowledgeMaintenance({ ...options, observations });
+}
+function buildMaintainerSystemContext(rootCatalog) {
+    return [
+        '## Memory Maintainer Mode',
+        '',
+        'You maintain Heddle workspace memory. You are not doing general coding work.',
+        'Use only memory tools. Do not ask for shell, code edit, web, or external tools.',
+        '',
+        'Hard invariants:',
+        '- Every durable note must be discoverable through the root catalog or a folder catalog.',
+        '- Read the root catalog first, then read the relevant folder catalog before writing.',
+        '- Search existing notes before creating a new note.',
+        '- Prefer updating existing notes over creating duplicates.',
+        '- Update folder catalogs whenever you create, rename, or retire a note.',
+        '- Update the root catalog only when a new high-value note or discovery path matters globally.',
+        '- Do not store secrets, credentials, private keys, tokens, or passwords.',
+        '- Skip low-value, duplicate, speculative, or one-turn scratch observations.',
+        '',
+        'Loaded root catalog:',
+        '',
+        rootCatalog,
+    ].join('\n');
+}
+function buildMaintenanceGoal(observations) {
+    return [
+        'Process these pending memory candidates into maintained cataloged memory.',
+        '',
+        ...observations.map((candidate, index) => [
+            `Candidate ${index + 1}: ${candidate.id}`,
+            `Summary: ${candidate.summary}`,
+            candidate.categoryHint ? `Category hint: ${candidate.categoryHint}` : undefined,
+            candidate.importance ? `Importance: ${candidate.importance}` : undefined,
+            candidate.confidence ? `Confidence: ${candidate.confidence}` : undefined,
+            candidate.evidence?.length ? `Evidence:\n${candidate.evidence.map((item) => `- ${item}`).join('\n')}` : undefined,
+            candidate.sourceRefs?.length ? `Source refs: ${candidate.sourceRefs.join(', ')}` : undefined,
+        ].filter((line) => Boolean(line)).join('\n')),
+        '',
+        'End with a concise summary of what memory notes or catalogs changed, or why candidates were skipped.',
+    ].join('\n\n');
+}
+async function appendMaintenanceRun(memoryRoot, run) {
+    const path = join(memoryRoot, '_maintenance', 'runs.jsonl');
+    await mkdir(dirname(path), { recursive: true });
+    await appendFile(path, `${JSON.stringify(run)}\n`, 'utf8');
+}
+async function appendCandidateStatusEvents(memoryRoot, candidateIds, runId, now) {
+    const path = join(memoryRoot, '_maintenance', 'candidates.jsonl');
+    await mkdir(dirname(path), { recursive: true });
+    const recordedAt = now().toISOString();
+    await appendFile(path, candidateIds.map((candidateId) => JSON.stringify({
+        kind: 'candidate_status',
+        candidateId,
+        status: 'processed',
+        runId,
+        recordedAt,
+    })).join('\n') + '\n', 'utf8');
+}
+async function readJsonlLines(path) {
+    try {
+        const raw = await readFile(path, 'utf8');
+        return raw.split(/\r?\n/u).filter((line) => line.trim());
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            return [];
+        }
+        throw error;
+    }
+}
+function parseJsonObject(line) {
+    try {
+        const parsed = JSON.parse(line);
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function isKnowledgeCandidate(value) {
+    return typeof value.id === 'string'
+        && typeof value.recordedAt === 'string'
+        && value.status === 'pending'
+        && typeof value.summary === 'string'
+        && (value.evidence === undefined || isStringArray(value.evidence))
+        && (value.categoryHint === undefined || typeof value.categoryHint === 'string')
+        && (value.importance === undefined || value.importance === 'low' || value.importance === 'medium' || value.importance === 'high')
+        && (value.confidence === undefined || value.confidence === 'user-stated' || value.confidence === 'tool-verified' || value.confidence === 'inferred' || value.confidence === 'historical')
+        && (value.sourceRefs === undefined || isStringArray(value.sourceRefs));
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === 'string');
+}
+function containsSecretLikeText(value) {
+    const normalized = value.toLowerCase();
+    return /\b(api[_ -]?key|password|passwd|private[_ -]?key|access[_ -]?token|refresh[_ -]?token|bearer\s+[a-z0-9._~+/=-]{12,})\b/i.test(value)
+        || /\bsecret\s*[:=]\s*\S{8,}/i.test(value)
+        || /\bsk-[a-z0-9_-]{12,}\b/i.test(value)
+        || normalized.includes('-----begin private key-----')
+        || normalized.includes('-----begin rsa private key-----')
+        || normalized.includes('-----begin openssh private key-----');
+}
+//# sourceMappingURL=maintainer.js.map

package/dist/src/core/memory/maintainer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"maintainer.js","sourceRoot":"","sources":["../../../../src/core/memory/maintainer.ts"],"names":[],"mappings":"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"}

package/dist/src/core/memory/maintenance-integration.d.ts

@@ -0,0 +1,20 @@
+import type { LlmAdapter } from '../llm/types.js';
+import type { TraceEvent } from '../types.js';
+import { type RunKnowledgeMaintenanceResult } from './maintainer.js';
+export type RunMaintenanceForRecordedCandidatesOptions = {
+    memoryRoot: string;
+    llm: LlmAdapter;
+    source: string;
+    trace: TraceEvent[];
+    maxSteps?: number;
+    lockTimeoutMs?: number;
+    lockStaleAfterMs?: number;
+    onTraceEvent?: (event: TraceEvent) => void;
+};
+export type RunMaintenanceForRecordedCandidatesResult = {
+    candidateIds: string[];
+    maintenance?: RunKnowledgeMaintenanceResult;
+    events: TraceEvent[];
+};
+export declare function runMaintenanceForRecordedCandidates(options: RunMaintenanceForRecordedCandidatesOptions): Promise<RunMaintenanceForRecordedCandidatesResult>;
+//# sourceMappingURL=maintenance-integration.d.ts.map

package/dist/src/core/memory/maintenance-integration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"maintenance-integration.d.ts","sourceRoot":"","sources":["../../../../src/core/memory/maintenance-integration.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAGL,KAAK,6BAA6B,EACnC,MAAM,iBAAiB,CAAC;AAOzB,MAAM,MAAM,0CAA0C,GAAG;IACvD,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,UAAU,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;CAC5C,CAAC;AAEF,MAAM,MAAM,yCAAyC,GAAG;IACtD,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,WAAW,CAAC,EAAE,6BAA6B,CAAC;IAC5C,MAAM,EAAE,UAAU,EAAE,CAAC;CACtB,CAAC;AAEF,wBAAsB,mCAAmC,CACvD,OAAO,EAAE,0CAA0C,GAClD,OAAO,CAAC,yCAAyC,CAAC,CAEpD"}