aidimag 1.0.0

package/dist/debug.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Debug channel for best-effort code paths.
+ *
+ * aidimag deliberately swallows errors in advisory paths (auto-sync, gap
+ * logging, embeddings, context regeneration) so they can never break a user
+ * command. The cost was observability: "why didn't X happen?" had no answer.
+ *
+ * `AIDIMAG_DEBUG=1 dim <cmd>` makes every swallowed error visible on stderr
+ * without changing behavior. Use `debugLog(scope, err)` in any catch that
+ * intentionally continues.
+ */
+export declare const DEBUG_ENABLED: boolean;
+/** Report a swallowed error when AIDIMAG_DEBUG is on. Never throws. */
+export declare function debugLog(scope: string, err: unknown): void;

package/dist/debug.js

@@ -0,0 +1,25 @@
+/**
+ * Debug channel for best-effort code paths.
+ *
+ * aidimag deliberately swallows errors in advisory paths (auto-sync, gap
+ * logging, embeddings, context regeneration) so they can never break a user
+ * command. The cost was observability: "why didn't X happen?" had no answer.
+ *
+ * `AIDIMAG_DEBUG=1 dim <cmd>` makes every swallowed error visible on stderr
+ * without changing behavior. Use `debugLog(scope, err)` in any catch that
+ * intentionally continues.
+ */
+export const DEBUG_ENABLED = process.env.AIDIMAG_DEBUG === "1" || process.env.AIDIMAG_DEBUG === "true";
+/** Report a swallowed error when AIDIMAG_DEBUG is on. Never throws. */
+export function debugLog(scope, err) {
+    if (!DEBUG_ENABLED)
+        return;
+    try {
+        const msg = err instanceof Error ? (err.stack ?? err.message) : String(err);
+        console.error(`[aidimag:debug] ${scope}: ${msg}`);
+    }
+    catch {
+        /* the debug channel itself must never throw */
+    }
+}
+//# sourceMappingURL=debug.js.map

package/dist/embeddings/provider.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Embedding providers — pluggable, zero-config auto-detection.
+ *
+ *   AIDIMAG_EMBEDDINGS = auto (default) | openai | ollama | off
+ *
+ * auto: OpenAI if OPENAI_API_KEY is set, else Ollama if reachable, else off
+ * (search degrades gracefully to FTS-only — aidimag never *requires* embeddings).
+ */
+export interface EmbeddingProvider {
+    readonly name: string;
+    readonly model: string;
+    readonly dim: number;
+    embed(texts: string[]): Promise<number[][]>;
+}
+/** Resolve the configured/auto-detected provider (cached per process). */
+export declare function getEmbeddingProvider(): Promise<EmbeddingProvider | null>;

package/dist/embeddings/provider.js

@@ -0,0 +1,100 @@
+/**
+ * Embedding providers — pluggable, zero-config auto-detection.
+ *
+ *   AIDIMAG_EMBEDDINGS = auto (default) | openai | ollama | off
+ *
+ * auto: OpenAI if OPENAI_API_KEY is set, else Ollama if reachable, else off
+ * (search degrades gracefully to FTS-only — aidimag never *requires* embeddings).
+ */
+const OLLAMA_URL = process.env.AIDIMAG_OLLAMA_URL ?? "http://localhost:11434";
+const OLLAMA_MODEL = process.env.AIDIMAG_OLLAMA_MODEL ?? "nomic-embed-text";
+const OPENAI_MODEL = process.env.AIDIMAG_OPENAI_MODEL ?? "text-embedding-3-small";
+class OpenAiProvider {
+    name = "openai";
+    model = OPENAI_MODEL;
+    dim = 1536;
+    async embed(texts) {
+        const res = await fetch("https://api.openai.com/v1/embeddings", {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
+            },
+            body: JSON.stringify({ model: this.model, input: texts }),
+        });
+        if (!res.ok)
+            throw new Error(`OpenAI embeddings: HTTP ${res.status} ${await res.text()}`);
+        const body = (await res.json());
+        return body.data.map((d) => d.embedding);
+    }
+}
+class OllamaProvider {
+    name = "ollama";
+    model = OLLAMA_MODEL;
+    dim;
+    constructor(dim) {
+        this.dim = dim;
+    }
+    async embed(texts) {
+        const out = [];
+        for (const text of texts) {
+            const res = await fetch(`${OLLAMA_URL}/api/embeddings`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ model: this.model, prompt: text }),
+            });
+            if (!res.ok)
+                throw new Error(`Ollama embeddings: HTTP ${res.status}`);
+            const body = (await res.json());
+            out.push(body.embedding);
+        }
+        return out;
+    }
+    static async detect() {
+        try {
+            const ctl = new AbortController();
+            const t = setTimeout(() => ctl.abort(), 1500);
+            const res = await fetch(`${OLLAMA_URL}/api/embeddings`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ model: OLLAMA_MODEL, prompt: "probe" }),
+                signal: ctl.signal,
+            });
+            clearTimeout(t);
+            if (!res.ok)
+                return null;
+            const body = (await res.json());
+            if (!body.embedding?.length)
+                return null;
+            return new OllamaProvider(body.embedding.length);
+        }
+        catch {
+            return null;
+        }
+    }
+}
+let cached;
+/** Resolve the configured/auto-detected provider (cached per process). */
+export async function getEmbeddingProvider() {
+    if (cached !== undefined)
+        return cached;
+    const mode = (process.env.AIDIMAG_EMBEDDINGS ?? "auto").toLowerCase();
+    if (mode === "off")
+        return (cached = null);
+    if (mode === "openai") {
+        if (!process.env.OPENAI_API_KEY)
+            throw new Error("AIDIMAG_EMBEDDINGS=openai but OPENAI_API_KEY is not set");
+        return (cached = new OpenAiProvider());
+    }
+    if (mode === "ollama") {
+        const p = await OllamaProvider.detect();
+        if (!p)
+            throw new Error(`AIDIMAG_EMBEDDINGS=ollama but Ollama is not reachable at ${OLLAMA_URL} (model: ${OLLAMA_MODEL})`);
+        return (cached = p);
+    }
+    // auto
+    if (process.env.OPENAI_API_KEY)
+        return (cached = new OpenAiProvider());
+    return (cached = await OllamaProvider.detect());
+}
+//# sourceMappingURL=provider.js.map

package/dist/embeddings/search.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Hybrid semantic recall — merges FTS keyword results with vector KNN using
+ * reciprocal-rank fusion, then applies the trust (status) penalty so VERIFIED
+ * memories outrank STALE ones regardless of similarity.
+ *
+ * Degrades gracefully: no provider / no vec extension → plain FTS search.
+ */
+import type { MemoryStore } from "../db/store.js";
+import type { MemoryEntry, MemorySearchOptions } from "../types.js";
+import { type EmbeddingProvider } from "./provider.js";
+/** Embed and index one memory (call after write/approve). No-op without a provider. */
+export declare function indexMemory(store: MemoryStore, entry: MemoryEntry): Promise<boolean>;
+/** Backfill embeddings for all memories missing one. Returns count indexed. */
+export declare function reindexAll(store: MemoryStore): Promise<{
+    indexed: number;
+    provider: EmbeddingProvider | null;
+}>;
+/** Hybrid search: FTS + KNN fused, status-aware. Falls back to FTS-only. */
+export declare function hybridSearch(store: MemoryStore, opts: MemorySearchOptions): Promise<{
+    results: MemoryEntry[];
+    semantic: boolean;
+}>;

package/dist/embeddings/search.js

@@ -0,0 +1,95 @@
+/**
+ * Hybrid semantic recall — merges FTS keyword results with vector KNN using
+ * reciprocal-rank fusion, then applies the trust (status) penalty so VERIFIED
+ * memories outrank STALE ones regardless of similarity.
+ *
+ * Degrades gracefully: no provider / no vec extension → plain FTS search.
+ */
+import { getEmbeddingProvider } from "./provider.js";
+import { debugLog } from "../debug.js";
+const RRF_K = 60;
+const STATUS_PENALTY = { VERIFIED: 0, UNVERIFIED: 0.004, STALE: 0.012, REFUTED: 0.02 };
+/** Embed and index one memory (call after write/approve). No-op without a provider. */
+export async function indexMemory(store, entry) {
+    const provider = await getEmbeddingProvider();
+    if (!provider || !store.vecAvailable)
+        return false;
+    if (!store.ensureVecTable(provider.model, provider.dim))
+        return false;
+    const [vec] = await provider.embed([embeddingText(entry)]);
+    store.upsertEmbedding(entry.id, vec);
+    return true;
+}
+/** Backfill embeddings for all memories missing one. Returns count indexed. */
+export async function reindexAll(store) {
+    const provider = await getEmbeddingProvider();
+    if (!provider || !store.vecAvailable)
+        return { indexed: 0, provider: null };
+    store.ensureVecTable(provider.model, provider.dim);
+    const ids = store.unembeddedIds();
+    let indexed = 0;
+    const BATCH = 16;
+    for (let i = 0; i < ids.length; i += BATCH) {
+        const batch = ids.slice(i, i + BATCH).map((id) => store.get(id)).filter((m) => !!m);
+        if (batch.length === 0)
+            continue;
+        const vectors = await provider.embed(batch.map(embeddingText));
+        batch.forEach((m, j) => store.upsertEmbedding(m.id, vectors[j]));
+        indexed += batch.length;
+    }
+    return { indexed, provider };
+}
+/** Hybrid search: FTS + KNN fused, status-aware. Falls back to FTS-only. */
+export async function hybridSearch(store, opts) {
+    const ftsResults = store.search(opts);
+    const provider = opts.query.trim() ? await getEmbeddingProvider().catch(() => null) : null;
+    if (!provider || !store.vecAvailable)
+        return { results: ftsResults, semantic: false };
+    let knnIds = [];
+    try {
+        const [qvec] = await provider.embed([opts.query]);
+        knnIds = store.knn(qvec, Math.max(opts.limit ?? 10, 10) * 2);
+    }
+    catch (err) {
+        // embedding/KNN failure → keyword-only results, never a broken search
+        debugLog("semantic search (fell back to keyword-only)", err);
+        return { results: ftsResults, semantic: false };
+    }
+    if (knnIds.length === 0)
+        return { results: ftsResults, semantic: false };
+    // reciprocal-rank fusion
+    const scores = new Map();
+    ftsResults.forEach((m, rank) => scores.set(m.id, (scores.get(m.id) ?? 0) + 1 / (RRF_K + rank + 1)));
+    knnIds.forEach(({ id }, rank) => scores.set(id, (scores.get(id) ?? 0) + 1 / (RRF_K + rank + 1)));
+    const byId = new Map(ftsResults.map((m) => [m.id, m]));
+    for (const { id } of knnIds) {
+        if (!byId.has(id)) {
+            const m = store.get(id);
+            if (m)
+                byId.set(id, m);
+        }
+    }
+    let candidates = [...byId.values()];
+    // re-apply filters that FTS applied but KNN bypassed
+    if (opts.kind)
+        candidates = candidates.filter((m) => m.kind === opts.kind);
+    if (opts.status)
+        candidates = candidates.filter((m) => m.status === opts.status);
+    else if (!opts.includeRefuted)
+        candidates = candidates.filter((m) => m.status !== "REFUTED");
+    if (opts.paths?.length) {
+        candidates = candidates.filter((m) => m.scope.paths.length === 0 ||
+            m.scope.paths.some((sp) => opts.paths.some((p) => p.startsWith(sp) || sp.startsWith(p))));
+    }
+    candidates.sort((a, b) => {
+        const sa = (scores.get(a.id) ?? 0) - (STATUS_PENALTY[a.status] ?? 0);
+        const sb = (scores.get(b.id) ?? 0) - (STATUS_PENALTY[b.status] ?? 0);
+        return sb - sa || b.confidence - a.confidence;
+    });
+    return { results: candidates.slice(0, Math.min(opts.limit ?? 10, 50)), semantic: true };
+}
+function embeddingText(m) {
+    const scope = [...m.scope.paths, ...m.scope.symbols].join(" ");
+    return `${m.kind}: ${m.claim}${scope ? `\nscope: ${scope}` : ""}`;
+}
+//# sourceMappingURL=search.js.map

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export * from "./types.js";
+export { MemoryStore, findRepoRoot, dbPathFor, AIDIMAG_DIR, DB_FILE } from "./db/store.js";
+export { mineCommits, readCommits, classifyCommit, scopeFromFiles } from "./capture/commit-miner.js";
+export { SESSION_END_PROMPT, proposalSummaryLine } from "./capture/session-extraction.js";
+export { verifyAll, verifyMemory, decayedConfidence } from "./verify/engine.js";
+export { runEvidence } from "./verify/runners.js";
+export { installGitHooks } from "./verify/hooks.js";
+export { getEmbeddingProvider } from "./embeddings/provider.js";
+export { hybridSearch, indexMemory, reindexAll } from "./embeddings/search.js";
+export { startSyncServer } from "./sync/server.js";
+export { sync, readCloudConfig, writeCloudConfig } from "./sync/client.js";

package/dist/index.js

@@ -0,0 +1,12 @@
+export * from "./types.js";
+export { MemoryStore, findRepoRoot, dbPathFor, AIDIMAG_DIR, DB_FILE } from "./db/store.js";
+export { mineCommits, readCommits, classifyCommit, scopeFromFiles } from "./capture/commit-miner.js";
+export { SESSION_END_PROMPT, proposalSummaryLine } from "./capture/session-extraction.js";
+export { verifyAll, verifyMemory, decayedConfidence } from "./verify/engine.js";
+export { runEvidence } from "./verify/runners.js";
+export { installGitHooks } from "./verify/hooks.js";
+export { getEmbeddingProvider } from "./embeddings/provider.js";
+export { hybridSearch, indexMemory, reindexAll } from "./embeddings/search.js";
+export { startSyncServer } from "./sync/server.js";
+export { sync, readCloudConfig, writeCloudConfig } from "./sync/client.js";
+//# sourceMappingURL=index.js.map

package/dist/knowledge/chunk.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Structure-aware chunking for large knowledge documents. We split on natural
+ * boundaries (Markdown headings first, then blank-line paragraphs) and pack
+ * sections up to ~chunkBytes, so a chunk is a coherent unit rather than a
+ * byte-count cut mid-sentence. Each chunk is summarized independently and the
+ * resulting claims are deduplicated across the whole document.
+ */
+/** Split text into coherent chunks no larger than ~chunkBytes (best effort). */
+export declare function chunkText(content: string, chunkBytes: number): string[];

package/dist/knowledge/chunk.js

@@ -0,0 +1,78 @@
+/**
+ * Structure-aware chunking for large knowledge documents. We split on natural
+ * boundaries (Markdown headings first, then blank-line paragraphs) and pack
+ * sections up to ~chunkBytes, so a chunk is a coherent unit rather than a
+ * byte-count cut mid-sentence. Each chunk is summarized independently and the
+ * resulting claims are deduplicated across the whole document.
+ */
+/** Split text into coherent chunks no larger than ~chunkBytes (best effort). */
+export function chunkText(content, chunkBytes) {
+    if (Buffer.byteLength(content, "utf8") <= chunkBytes)
+        return [content];
+    // First pass: break at Markdown headings (keep the heading with its body).
+    const sections = splitOnHeadings(content);
+    const chunks = [];
+    let buf = "";
+    const flush = () => {
+        if (buf.trim())
+            chunks.push(buf.trim());
+        buf = "";
+    };
+    for (const section of sections) {
+        // A single section bigger than the budget → split it further on paragraphs.
+        if (Buffer.byteLength(section, "utf8") > chunkBytes) {
+            flush();
+            for (const part of splitOnParagraphs(section, chunkBytes))
+                chunks.push(part);
+            continue;
+        }
+        if (buf && Buffer.byteLength(buf + "\n\n" + section, "utf8") > chunkBytes)
+            flush();
+        buf = buf ? buf + "\n\n" + section : section;
+    }
+    flush();
+    return chunks.length ? chunks : [content];
+}
+/** Group lines into sections that each start at a Markdown heading. */
+function splitOnHeadings(content) {
+    const lines = content.split("\n");
+    const sections = [];
+    let current = [];
+    for (const line of lines) {
+        if (/^#{1,6}\s/.test(line) && current.some((l) => l.trim())) {
+            sections.push(current.join("\n"));
+            current = [];
+        }
+        current.push(line);
+    }
+    if (current.length)
+        sections.push(current.join("\n"));
+    return sections;
+}
+/** Pack blank-line-separated paragraphs up to the byte budget. */
+function splitOnParagraphs(text, chunkBytes) {
+    const paras = text.split(/\n\s*\n/);
+    const out = [];
+    let buf = "";
+    for (const para of paras) {
+        if (buf && Buffer.byteLength(buf + "\n\n" + para, "utf8") > chunkBytes) {
+            out.push(buf.trim());
+            buf = "";
+        }
+        // A single paragraph over budget: hard-wrap by characters as a last resort.
+        if (Buffer.byteLength(para, "utf8") > chunkBytes) {
+            if (buf.trim()) {
+                out.push(buf.trim());
+                buf = "";
+            }
+            for (let i = 0; i < para.length; i += chunkBytes)
+                out.push(para.slice(i, i + chunkBytes));
+            continue;
+        }
+        buf = buf ? buf + "\n\n" + para : para;
+    }
+    if (buf.trim())
+        out.push(buf.trim());
+    return out;
+}
+//# sourceMappingURL=chunk.js.map

package/dist/knowledge/extract.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Shared claim-extraction contract for knowledge ingestion. Both summarizer paths
+ * use this so they produce identical, reviewable output:
+ *   - the LLM fallback (`dim knowledge sync`) feeds these instructions to a model;
+ *   - the MCP `knowledge_ingest` prompt feeds them to the connected agent.
+ *
+ * The extractor turns a project document into typed, scoped, FALSIFIABLE claims —
+ * never a single blob. Claims become proposals (source `knowledge:<doc>`) and, once
+ * approved with `dim review`, PINNED memories.
+ */
+import type { GuardrailLevel, MemoryKind } from "../types.js";
+export interface ExtractedClaim {
+    kind: MemoryKind;
+    claim: string;
+    paths?: string[];
+    symbols?: string[];
+    /** only for kind === "GUARDRAIL" */
+    guardrailLevel?: GuardrailLevel;
+    /** short note on why this is durable / where in the doc it came from */
+    rationale?: string;
+    /** optional STATIC_CHECK shell command that passes iff the claim holds */
+    staticCheck?: string;
+}
+export declare const KNOWLEDGE_EXTRACT_INSTRUCTIONS = "You are extracting durable, project-specific knowledge from a document a developer dropped into the knowledge inbox (a design doc, ADR, style guide, runbook, or notes).\n\nTurn it into a small set of FALSIFIABLE claims. Rules:\n\n1. Only DURABLE, NON-OBVIOUS facts about THIS project \u2014 rules, decisions, architecture, invariants, guardrails, procedures. Skip generic advice, tutorials, and anything a quick file read already shows.\n2. Write each claim as a checkable statement. Bad: \"auth is complex\". Good: \"JWT refresh in src/auth/refresh.ts must run before the middleware chain; reordering breaks session renewal\".\n3. Pick the right kind:\n   - DECISION: a choice + the rejected alternative\n   - CONVENTION: a rule the repo follows\n   - GOTCHA: surprising behavior that costs time\n   - FAILED_APPROACH: something tried that did NOT work\n   - ARCHITECTURE: how components fit together\n   - INVARIANT: something that must always/never hold\n   - GUARDRAIL: a behavioral rule for future agents \u2014 set guardrail_level to \"never\" (refuse), \"ask-first\" (confirm), or \"always\" (do automatically)\n   - SKILL: a reusable step-by-step procedure (write the steps as \"1) ... 2) ...\")\n   - TODO_CONTEXT: unfinished work + the context to resume it\n4. Scope each claim with paths/symbols it applies to when the document names them; otherwise leave them empty (repo-wide).\n5. Extract 0\u201312 claims. Zero is fine. Do NOT pad, and do NOT invent rules the document doesn't support.\n\nRespond with ONLY a JSON object of this exact shape:\n{\"claims\":[{\"kind\":\"CONVENTION\",\"claim\":\"...\",\"paths\":[\"src/x\"],\"symbols\":[],\"guardrail_level\":null,\"rationale\":\"...\"}]}";
+/** Build the user message for the LLM: instructions + the document. */
+export declare function buildExtractionUser(filename: string, content: string): string;
+/**
+ * Tolerantly parse a model/agent response into validated claims. Accepts a bare
+ * array or an object with a `claims` array, and ignores anything malformed rather
+ * than throwing — a bad doc should never crash ingestion.
+ */
+export declare function parseClaims(raw: string): ExtractedClaim[];
+/** Collapse claims repeated across chunks (normalized text match). */
+export declare function dedupeClaims(claims: ExtractedClaim[]): ExtractedClaim[];

package/dist/knowledge/extract.js

@@ -0,0 +1,113 @@
+/**
+ * Shared claim-extraction contract for knowledge ingestion. Both summarizer paths
+ * use this so they produce identical, reviewable output:
+ *   - the LLM fallback (`dim knowledge sync`) feeds these instructions to a model;
+ *   - the MCP `knowledge_ingest` prompt feeds them to the connected agent.
+ *
+ * The extractor turns a project document into typed, scoped, FALSIFIABLE claims —
+ * never a single blob. Claims become proposals (source `knowledge:<doc>`) and, once
+ * approved with `dim review`, PINNED memories.
+ */
+const KINDS = [
+    "DECISION", "CONVENTION", "GOTCHA", "FAILED_APPROACH",
+    "ARCHITECTURE", "INVARIANT", "TODO_CONTEXT", "GUARDRAIL", "SKILL",
+];
+const GUARDRAIL_LEVELS = ["never", "ask-first", "always"];
+export const KNOWLEDGE_EXTRACT_INSTRUCTIONS = `You are extracting durable, project-specific knowledge from a document a developer dropped into the knowledge inbox (a design doc, ADR, style guide, runbook, or notes).
+
+Turn it into a small set of FALSIFIABLE claims. Rules:
+
+1. Only DURABLE, NON-OBVIOUS facts about THIS project — rules, decisions, architecture, invariants, guardrails, procedures. Skip generic advice, tutorials, and anything a quick file read already shows.
+2. Write each claim as a checkable statement. Bad: "auth is complex". Good: "JWT refresh in src/auth/refresh.ts must run before the middleware chain; reordering breaks session renewal".
+3. Pick the right kind:
+   - DECISION: a choice + the rejected alternative
+   - CONVENTION: a rule the repo follows
+   - GOTCHA: surprising behavior that costs time
+   - FAILED_APPROACH: something tried that did NOT work
+   - ARCHITECTURE: how components fit together
+   - INVARIANT: something that must always/never hold
+   - GUARDRAIL: a behavioral rule for future agents — set guardrail_level to "never" (refuse), "ask-first" (confirm), or "always" (do automatically)
+   - SKILL: a reusable step-by-step procedure (write the steps as "1) ... 2) ...")
+   - TODO_CONTEXT: unfinished work + the context to resume it
+4. Scope each claim with paths/symbols it applies to when the document names them; otherwise leave them empty (repo-wide).
+5. Extract 0–12 claims. Zero is fine. Do NOT pad, and do NOT invent rules the document doesn't support.
+
+Respond with ONLY a JSON object of this exact shape:
+{"claims":[{"kind":"CONVENTION","claim":"...","paths":["src/x"],"symbols":[],"guardrail_level":null,"rationale":"..."}]}`;
+/** Build the user message for the LLM: instructions + the document. */
+export function buildExtractionUser(filename, content) {
+    return `Document: ${filename}\n\n----- BEGIN DOCUMENT -----\n${content}\n----- END DOCUMENT -----`;
+}
+function asStringArray(v) {
+    if (!Array.isArray(v))
+        return undefined;
+    const out = v.filter((x) => typeof x === "string" && x.trim().length > 0);
+    return out.length ? out : undefined;
+}
+/**
+ * Tolerantly parse a model/agent response into validated claims. Accepts a bare
+ * array or an object with a `claims` array, and ignores anything malformed rather
+ * than throwing — a bad doc should never crash ingestion.
+ */
+export function parseClaims(raw) {
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch {
+        // last resort: pull the first {...} or [...] block out of chatty output
+        const m = raw.match(/\{[\s\S]*\}|\[[\s\S]*\]/);
+        if (!m)
+            return [];
+        try {
+            data = JSON.parse(m[0]);
+        }
+        catch {
+            return [];
+        }
+    }
+    const list = Array.isArray(data)
+        ? data
+        : data?.claims;
+    if (!Array.isArray(list))
+        return [];
+    const claims = [];
+    for (const item of list) {
+        const kind = String(item?.kind ?? "").toUpperCase();
+        const claim = typeof item?.claim === "string" ? item.claim.trim() : "";
+        if (!claim || !KINDS.includes(kind))
+            continue;
+        const out = { kind, claim };
+        const paths = asStringArray(item.paths);
+        const symbols = asStringArray(item.symbols);
+        if (paths)
+            out.paths = paths;
+        if (symbols)
+            out.symbols = symbols;
+        if (typeof item.rationale === "string" && item.rationale.trim())
+            out.rationale = item.rationale.trim();
+        const sc = item.static_check ?? item.staticCheck;
+        if (typeof sc === "string" && sc.trim())
+            out.staticCheck = sc.trim();
+        if (kind === "GUARDRAIL") {
+            const lvl = String(item.guardrail_level ?? item.guardrailLevel ?? "ask-first").toLowerCase();
+            out.guardrailLevel = GUARDRAIL_LEVELS.includes(lvl) ? lvl : "ask-first";
+        }
+        claims.push(out);
+    }
+    return dedupeClaims(claims);
+}
+/** Collapse claims repeated across chunks (normalized text match). */
+export function dedupeClaims(claims) {
+    const seen = new Set();
+    const out = [];
+    for (const c of claims) {
+        const key = c.claim.toLowerCase().replace(/\s+/g, " ").trim();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(c);
+    }
+    return out;
+}
+//# sourceMappingURL=extract.js.map

package/dist/knowledge/ingest.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Knowledge ingestion pipeline (KNOWLEDGEBASE_DESIGN.md).
+ *
+ * Drop docs into the `knowledge/` inbox → they're classified, (chunked and)
+ * summarized into typed claims → queued as proposals (source `knowledge:<doc>`,
+ * pin-on-approve) → a plain-text summary is written and the original is backed up
+ * to .aidimag/knowledge/processed/ before the inbox copy is removed.
+ * PDF and DOCX files have their text extracted (pdf-parse / mammoth) first.
+ *
+ * Trust gate: claims become PINNED memories only after `dim review` (unless the
+ * repo opts out with knowledge.requireReview = false). Nothing is ever deleted —
+ * unsupported files move to .aidimag/knowledge/skipped/ with a reason.
+ */
+import type { MemoryStore } from "../db/store.js";
+import type { ResolvedKnowledgeConfig } from "../config.js";
+import type { ExtractedClaim } from "./extract.js";
+export interface PendingDoc {
+    file: string;
+    abs: string;
+    content: string;
+    hash: string;
+    bytes: number;
+}
+export interface SkipCandidate {
+    file: string;
+    reason: string;
+}
+export interface DocResult {
+    file: string;
+    hash: string;
+    claimCount: number;
+    proposalIds: string[];
+    memoryIds: string[];
+    pinned: boolean;
+}
+export interface IngestReport {
+    processed: DocResult[];
+    pendingNoSummarizer: string[];
+    duplicates: string[];
+    skipped: SkipCandidate[];
+    summarizer: string | null;
+}
+interface ManifestEntry {
+    file: string;
+    hash: string;
+    date: string;
+    via: string;
+    claimCount: number;
+    proposalIds: string[];
+    memoryIds: string[];
+}
+interface Manifest {
+    version: number;
+    docs: ManifestEntry[];
+}
+export declare function readManifest(root: string): Manifest;
+export declare function classifyInbox(root: string, cfg: ResolvedKnowledgeConfig): Promise<{
+    pending: PendingDoc[];
+    toSkip: SkipCandidate[];
+}>;
+/**
+ * Turn extracted claims into proposals and retire the inbox file safely.
+ * Used by both the LLM path and the MCP agent path (which supplies its own claims).
+ */
+export declare function finalizeDoc(store: MemoryStore, root: string, cfg: ResolvedKnowledgeConfig, doc: {
+    file: string;
+    hash: string;
+    abs?: string;
+}, claims: ExtractedClaim[], via: string): DocResult;
+export declare function ingestAll(store: MemoryStore, root: string, cfg: ResolvedKnowledgeConfig): Promise<IngestReport>;
+export interface KnowledgeStatus {
+    folder: string;
+    pending: PendingDoc[];
+    unsupported: SkipCandidate[];
+    skippedOnDisk: string[];
+    processed: ManifestEntry[];
+}
+export declare function knowledgeStatus(root: string, cfg: ResolvedKnowledgeConfig): Promise<KnowledgeStatus>;
+export {};