linksee-memory 0.0.1

package/dist/db/schema.sql

@@ -0,0 +1,199 @@
+-- linksee-memory schema v0.0.2
+-- Single-file SQLite store for cross-agent structured memory.
+-- Layers: 1=facts (entities), 2=associations (edges), 3=patterns (meanings), 4=events (time-series), 5=file-state (diff cache).
+-- v2 adds: FTS5 full-text search, consolidations audit, momentum cache on entities.
+
+-- ============================================================
+-- Layer 1: Facts — entities (people / companies / projects / concepts)
+-- ============================================================
+CREATE TABLE IF NOT EXISTS entities (
+  id              INTEGER PRIMARY KEY AUTOINCREMENT,
+  kind            TEXT NOT NULL CHECK (kind IN ('person', 'company', 'project', 'concept', 'file', 'other')),
+  name            TEXT NOT NULL,
+  canonical_key   TEXT UNIQUE,
+  attributes      TEXT,
+  momentum_score  REAL NOT NULL DEFAULT 0.0,      -- 0-10 cached; refreshed on event insert
+  momentum_at     INTEGER,                         -- when momentum was last computed
+  created_at      INTEGER NOT NULL DEFAULT (unixepoch()),
+  updated_at      INTEGER NOT NULL DEFAULT (unixepoch())
+);
+
+CREATE INDEX IF NOT EXISTS idx_entities_kind ON entities(kind);
+CREATE INDEX IF NOT EXISTS idx_entities_key  ON entities(canonical_key);
+
+-- ============================================================
+-- Layer 3: Meanings — 6-layer structured memory per entity
+-- ============================================================
+CREATE TABLE IF NOT EXISTS memories (
+  id              INTEGER PRIMARY KEY AUTOINCREMENT,
+  entity_id       INTEGER NOT NULL REFERENCES entities(id) ON DELETE CASCADE,
+  layer           TEXT NOT NULL CHECK (layer IN (
+                    'goal', 'context', 'emotion', 'implementation', 'caveat', 'learning'
+                  )),
+  content         TEXT NOT NULL,
+  importance      REAL NOT NULL DEFAULT 0.5,
+  protected       INTEGER NOT NULL DEFAULT 0,
+  source          TEXT,
+  created_at      INTEGER NOT NULL DEFAULT (unixepoch()),
+  last_accessed_at INTEGER NOT NULL DEFAULT (unixepoch()),
+  access_count    INTEGER NOT NULL DEFAULT 0
+);
+
+CREATE INDEX IF NOT EXISTS idx_memories_entity     ON memories(entity_id);
+CREATE INDEX IF NOT EXISTS idx_memories_layer      ON memories(layer);
+CREATE INDEX IF NOT EXISTS idx_memories_importance ON memories(importance DESC);
+CREATE INDEX IF NOT EXISTS idx_memories_protected  ON memories(protected);
+
+CREATE TRIGGER IF NOT EXISTS trg_protect_caveat
+  AFTER INSERT ON memories
+  WHEN NEW.layer = 'caveat'
+  BEGIN
+    UPDATE memories SET protected = 1 WHERE id = NEW.id;
+  END;
+
+-- ============================================================
+-- FTS5 full-text search over memory content (Day 2)
+-- BM25-ranked retrieval; combined with heat + momentum at query time.
+-- ============================================================
+-- trigram tokenizer indexes 3-character substrings — works for both English (case-insensitive
+-- via remove_diacritics) AND Japanese/CJK (no word boundaries needed).
+CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(
+  content,
+  content='memories',
+  content_rowid='id',
+  tokenize='trigram remove_diacritics 1'
+);
+
+CREATE TRIGGER IF NOT EXISTS trg_memories_fts_ai
+  AFTER INSERT ON memories BEGIN
+    INSERT INTO memories_fts(rowid, content) VALUES (NEW.id, NEW.content);
+  END;
+
+CREATE TRIGGER IF NOT EXISTS trg_memories_fts_ad
+  AFTER DELETE ON memories BEGIN
+    INSERT INTO memories_fts(memories_fts, rowid, content) VALUES('delete', OLD.id, OLD.content);
+  END;
+
+CREATE TRIGGER IF NOT EXISTS trg_memories_fts_au
+  AFTER UPDATE ON memories BEGIN
+    INSERT INTO memories_fts(memories_fts, rowid, content) VALUES('delete', OLD.id, OLD.content);
+    INSERT INTO memories_fts(rowid, content) VALUES (NEW.id, NEW.content);
+  END;
+
+-- ============================================================
+-- Layer 2: Associations — graph edges between entities
+-- ============================================================
+CREATE TABLE IF NOT EXISTS edges (
+  id            INTEGER PRIMARY KEY AUTOINCREMENT,
+  from_id       INTEGER NOT NULL REFERENCES entities(id) ON DELETE CASCADE,
+  to_id         INTEGER NOT NULL REFERENCES entities(id) ON DELETE CASCADE,
+  relation      TEXT NOT NULL,
+  weight        REAL NOT NULL DEFAULT 1.0,
+  attributes    TEXT,
+  created_at    INTEGER NOT NULL DEFAULT (unixepoch()),
+  UNIQUE(from_id, to_id, relation)
+);
+
+CREATE INDEX IF NOT EXISTS idx_edges_from ON edges(from_id);
+CREATE INDEX IF NOT EXISTS idx_edges_to   ON edges(to_id);
+CREATE INDEX IF NOT EXISTS idx_edges_rel  ON edges(relation);
+
+-- ============================================================
+-- Layer 4: Events — time-series log with importance markers
+-- ============================================================
+CREATE TABLE IF NOT EXISTS events (
+  id            INTEGER PRIMARY KEY AUTOINCREMENT,
+  entity_id     INTEGER REFERENCES entities(id) ON DELETE CASCADE,
+  kind          TEXT NOT NULL,
+  payload       TEXT,
+  occurred_at   INTEGER NOT NULL DEFAULT (unixepoch())
+);
+
+CREATE INDEX IF NOT EXISTS idx_events_entity   ON events(entity_id);
+CREATE INDEX IF NOT EXISTS idx_events_occurred ON events(occurred_at DESC);
+CREATE INDEX IF NOT EXISTS idx_events_kind     ON events(kind);
+
+-- ============================================================
+-- Layer 5: File snapshots — diff cache for read_smart (Day 3)
+-- ============================================================
+CREATE TABLE IF NOT EXISTS file_snapshots (
+  path           TEXT PRIMARY KEY,
+  content_hash   TEXT NOT NULL,
+  mtime          INTEGER NOT NULL,
+  size_bytes     INTEGER,
+  chunks         TEXT,
+  last_read_at   INTEGER NOT NULL DEFAULT (unixepoch()),
+  read_count     INTEGER NOT NULL DEFAULT 1
+);
+
+CREATE INDEX IF NOT EXISTS idx_file_mtime ON file_snapshots(mtime);
+
+CREATE TABLE IF NOT EXISTS file_facts (
+  id              INTEGER PRIMARY KEY AUTOINCREMENT,
+  file_path       TEXT NOT NULL REFERENCES file_snapshots(path) ON DELETE CASCADE,
+  chunk_hash      TEXT,
+  fact            TEXT NOT NULL,
+  layer           TEXT CHECK (layer IN ('goal', 'context', 'emotion', 'implementation', 'caveat', 'learning')),
+  extracted_at    INTEGER NOT NULL DEFAULT (unixepoch())
+);
+
+CREATE INDEX IF NOT EXISTS idx_file_facts_path ON file_facts(file_path);
+
+-- ============================================================
+-- Sessions — track which agent / conversation produced memories
+-- ============================================================
+CREATE TABLE IF NOT EXISTS sessions (
+  id            TEXT PRIMARY KEY,
+  agent_kind    TEXT,
+  started_at    INTEGER NOT NULL DEFAULT (unixepoch()),
+  last_seen_at  INTEGER NOT NULL DEFAULT (unixepoch())
+);
+
+-- ============================================================
+-- Session file edits (v3) — conversation↔file linkage.
+-- Each row: "during session S, at turn T, memory M mentions editing file F".
+-- This is the table that breaks the Mem0 "flat metatag" wall:
+-- memories describe WHY, file_edits tie the WHY to concrete filesystem changes.
+-- ============================================================
+CREATE TABLE IF NOT EXISTS session_file_edits (
+  id              INTEGER PRIMARY KEY AUTOINCREMENT,
+  session_id      TEXT NOT NULL,                    -- Claude Code session uuid
+  memory_id       INTEGER REFERENCES memories(id) ON DELETE SET NULL,
+  file_path       TEXT NOT NULL,
+  operation       TEXT NOT NULL CHECK (operation IN ('read', 'edit', 'write', 'bash', 'other')),
+  turn_uuid       TEXT,
+  context_snippet TEXT,                             -- 1-2 line distilled "why this edit"
+  occurred_at     INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_sfe_session ON session_file_edits(session_id);
+CREATE INDEX IF NOT EXISTS idx_sfe_file    ON session_file_edits(file_path);
+CREATE INDEX IF NOT EXISTS idx_sfe_memory  ON session_file_edits(memory_id);
+CREATE INDEX IF NOT EXISTS idx_sfe_when    ON session_file_edits(occurred_at DESC);
+
+-- ============================================================
+-- Consolidations audit (Day 2) — trail of what got compressed into what
+-- ============================================================
+CREATE TABLE IF NOT EXISTS consolidations (
+  id              INTEGER PRIMARY KEY AUTOINCREMENT,
+  learning_id     INTEGER REFERENCES memories(id) ON DELETE SET NULL,
+  replaced_ids    TEXT NOT NULL,         -- JSON array of deleted memory ids
+  replaced_count  INTEGER NOT NULL,
+  entity_id       INTEGER REFERENCES entities(id) ON DELETE CASCADE,
+  original_layer  TEXT NOT NULL,
+  created_at      INTEGER NOT NULL DEFAULT (unixepoch())
+);
+
+CREATE INDEX IF NOT EXISTS idx_consolidations_entity ON consolidations(entity_id);
+
+-- ============================================================
+-- Meta — schema version tracking
+-- ============================================================
+CREATE TABLE IF NOT EXISTS meta (
+  key           TEXT PRIMARY KEY,
+  value         TEXT NOT NULL
+);
+
+INSERT OR IGNORE INTO meta (key, value) VALUES ('schema_version', '4');
+INSERT OR IGNORE INTO meta (key, value) VALUES ('created_at', CAST(unixepoch() AS TEXT));
+UPDATE meta SET value = '4' WHERE key = 'schema_version' AND value IN ('1', '2', '3');

package/dist/lib/consolidate.d.ts

@@ -0,0 +1,12 @@
+import type Database from 'better-sqlite3';
+export interface ConsolidateResult {
+    scanned: number;
+    clustersCompressed: number;
+    memoriesReplaced: number;
+    memoriesDropped: number;
+    learningIdsCreated: number[];
+}
+export declare function consolidate(db: Database.Database, opts?: {
+    scope?: 'all' | 'session';
+    min_age_days?: number;
+}): ConsolidateResult;

package/dist/lib/consolidate.js

@@ -0,0 +1,148 @@
+// Sleep-mode consolidation: cluster stale low-importance memories,
+// summarize into a single `learning`-layer entry, delete originals.
+// Implements Michie's memory principle 4 (sleep consolidation).
+//
+// Strategy (rule-based, no LLM required):
+//   1. Find candidates: layer IN (context, emotion, implementation),
+//      protected=0, cold (heat<30), older than 7 days, cluster size >= 2.
+//   2. Group by (entity_id, layer).
+//   3. Emit a structured summary into `learning` layer (protected=1),
+//      then delete originals.
+//   4. Per-run forget-sweep drops expired memories that didn't cluster.
+import { computeHeat } from './heat-index.js';
+import { decideForgetting } from './forgetting.js';
+const CLUSTER_LAYERS = ['context', 'emotion', 'implementation'];
+const DEFAULT_MIN_AGE_DAYS = 7;
+const MAX_HEAT = 30;
+const MIN_CLUSTER_SIZE = 2;
+export function consolidate(db, opts = {}) {
+    const now = Math.floor(Date.now() / 1000);
+    const minAgeDays = opts.min_age_days ?? DEFAULT_MIN_AGE_DAYS;
+    const ageCutoff = now - minAgeDays * 86400;
+    // Fetch candidates with age threshold. 'session' scope → same query currently
+    // (Day 2: session filter needs session_id plumbing; will add when sessions
+    // table is actually populated by the MCP server).
+    const layerPlaceholders = CLUSTER_LAYERS.map(() => '?').join(',');
+    const rows = db
+        .prepare(`
+      SELECT m.id, m.entity_id, m.layer, m.content, m.importance,
+             m.last_accessed_at, m.access_count, m.created_at, m.protected,
+             e.name as entity_name
+      FROM memories m
+      JOIN entities e ON e.id = m.entity_id
+      WHERE m.protected = 0
+        AND m.layer IN (${layerPlaceholders})
+        AND m.created_at <= ?
+      ORDER BY m.entity_id, m.layer, m.created_at
+      `)
+        .all(...CLUSTER_LAYERS, ageCutoff);
+    // Filter to cold-heat memories
+    const cold = rows.filter((r) => {
+        const daysSince = (now - r.last_accessed_at) / 86400;
+        const heat = computeHeat({
+            accessesLast30d: daysSince < 30 ? r.access_count : 0,
+            accessesLast90d: daysSince < 90 ? r.access_count : 0,
+            daysSinceLastAccess: daysSince,
+            totalAccesses: r.access_count,
+            baseImportance: r.importance,
+        });
+        return heat.score < MAX_HEAT;
+    });
+    // Group by (entity_id, layer)
+    const groups = new Map();
+    for (const r of cold) {
+        const key = `${r.entity_id}::${r.layer}`;
+        const arr = groups.get(key) ?? [];
+        arr.push(r);
+        groups.set(key, arr);
+    }
+    const result = {
+        scanned: rows.length,
+        clustersCompressed: 0,
+        memoriesReplaced: 0,
+        memoriesDropped: 0,
+        learningIdsCreated: [],
+    };
+    const insertLearning = db.prepare(`INSERT INTO memories (entity_id, layer, content, importance, protected, source)
+     VALUES (?, 'learning', ?, ?, 1, ?)`);
+    const deleteMemory = db.prepare('DELETE FROM memories WHERE id = ?');
+    const insertAudit = db.prepare(`INSERT INTO consolidations (learning_id, replaced_ids, replaced_count, entity_id, original_layer)
+     VALUES (?, ?, ?, ?, ?)`);
+    const insertEvent = db.prepare('INSERT INTO events (entity_id, kind, payload) VALUES (?, ?, ?)');
+    const tx = db.transaction(() => {
+        for (const [key, cluster] of groups) {
+            if (cluster.length < MIN_CLUSTER_SIZE)
+                continue;
+            const [entityIdStr, layer] = key.split('::');
+            const entityId = Number(entityIdStr);
+            const entityName = cluster[0].entity_name;
+            // Sort by importance desc, take top 3 as exemplars
+            const byImp = [...cluster].sort((a, b) => b.importance - a.importance);
+            const exemplars = byImp.slice(0, 3).map((c) => ({
+                fragment: c.content.length > 200 ? c.content.slice(0, 200) + '…' : c.content,
+                when: new Date(c.created_at * 1000).toISOString().slice(0, 10),
+                importance: c.importance,
+            }));
+            const timestamps = cluster.map((c) => c.created_at);
+            const earliest = new Date(Math.min(...timestamps) * 1000).toISOString().slice(0, 10);
+            const latest = new Date(Math.max(...timestamps) * 1000).toISOString().slice(0, 10);
+            const avgImp = cluster.reduce((s, c) => s + c.importance, 0) / cluster.length;
+            const summary = {
+                source: 'consolidate',
+                original_layer: layer,
+                count: cluster.length,
+                period: { from: earliest, to: latest },
+                pattern: `${cluster.length} cold observations on "${entityName}" (${layer}) consolidated during sleep`,
+                exemplars,
+                replaced_ids: cluster.map((c) => c.id),
+            };
+            const learningImportance = Math.max(avgImp, 0.55); // summaries are slightly more important than their avg source
+            const sourceMeta = JSON.stringify({ origin: 'consolidate', replaced: cluster.length });
+            const ins = insertLearning.run(entityId, JSON.stringify(summary, null, 2), learningImportance, sourceMeta);
+            const learningId = Number(ins.lastInsertRowid);
+            result.learningIdsCreated.push(learningId);
+            insertAudit.run(learningId, JSON.stringify(cluster.map((c) => c.id)), cluster.length, entityId, layer);
+            for (const c of cluster)
+                deleteMemory.run(c.id);
+            insertEvent.run(entityId, 'memory_consolidated', JSON.stringify({ learning_id: learningId, count: cluster.length, layer }));
+            result.clustersCompressed++;
+            result.memoriesReplaced += cluster.length;
+        }
+    });
+    tx();
+    // Post-consolidate: forget-sweep remaining non-clustered cold memories
+    const remaining = db
+        .prepare('SELECT id, layer, importance, access_count, last_accessed_at, protected FROM memories WHERE protected = 0')
+        .all();
+    const toDrop = [];
+    for (const r of remaining) {
+        const daysSince = (now - r.last_accessed_at) / 86400;
+        const heat = computeHeat({
+            accessesLast30d: daysSince < 30 ? r.access_count : 0,
+            accessesLast90d: daysSince < 90 ? r.access_count : 0,
+            daysSinceLastAccess: daysSince,
+            totalAccesses: r.access_count,
+            baseImportance: r.importance,
+        });
+        const action = decideForgetting({
+            daysSinceLastAccess: daysSince,
+            importance: r.importance,
+            heatScore: heat.score,
+            protected: r.protected === 1,
+            layer: r.layer,
+        });
+        if (action === 'drop')
+            toDrop.push(r.id);
+    }
+    if (toDrop.length > 0) {
+        const del = db.prepare('DELETE FROM memories WHERE id = ?');
+        const tx2 = db.transaction((ids) => {
+            for (const id of ids)
+                del.run(id);
+        });
+        tx2(toDrop);
+        result.memoriesDropped = toDrop.length;
+    }
+    return result;
+}
+//# sourceMappingURL=consolidate.js.map

package/dist/lib/file-chunker.d.ts

@@ -0,0 +1,12 @@
+export type ChunkKind = 'function' | 'class' | 'variable' | 'import' | 'heading' | 'python_def' | 'python_class' | 'python_preamble' | 'fixed';
+export interface Chunk {
+    id: string;
+    kind: ChunkKind;
+    start_line: number;
+    end_line: number;
+    hash: string;
+    content: string;
+}
+export declare function shortHash(s: string): string;
+export declare function hashFile(content: string): string;
+export declare function chunkFile(path: string, content: string): Chunk[];

package/dist/lib/file-chunker.js

@@ -0,0 +1,250 @@
+// File chunking for read_smart diff cache.
+// Splits files into semantic chunks so re-reads can return only modified regions.
+//   .ts/.js/.jsx/.tsx/.mjs/.cjs → AST via @babel/parser (top-level decls)
+//   .py                         → indent-based (top-level def/class)
+//   .md                         → h2/h3 headings
+//   else                        → fixed 100-line windows
+import { parse as babelParse } from '@babel/parser';
+import { createHash } from 'node:crypto';
+import { extname } from 'node:path';
+export function shortHash(s) {
+    return createHash('sha256').update(s).digest('hex').slice(0, 16);
+}
+export function hashFile(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+function extractLines(content, start, end) {
+    return content.split('\n').slice(start - 1, end).join('\n');
+}
+export function chunkFile(path, content) {
+    const ext = extname(path).toLowerCase();
+    try {
+        if (['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'].includes(ext)) {
+            return chunkTsJs(content);
+        }
+        if (ext === '.py')
+            return chunkPython(content);
+        if (ext === '.md' || ext === '.markdown')
+            return chunkMarkdown(content);
+    }
+    catch {
+        // parse failures fall back to fixed
+    }
+    return chunkFixed(content, 100);
+}
+// ============================================================
+// TypeScript / JavaScript — AST-based
+// ============================================================
+function chunkTsJs(content) {
+    const ast = babelParse(content, {
+        sourceType: 'unambiguous',
+        plugins: ['typescript', 'jsx', 'decorators-legacy'],
+        errorRecovery: true,
+        allowImportExportEverywhere: true,
+        allowReturnOutsideFunction: true,
+    });
+    const chunks = [];
+    const importNodes = [];
+    for (const node of ast.program.body) {
+        if (!node.loc)
+            continue;
+        const start = node.loc.start.line;
+        const end = node.loc.end.line;
+        if (node.type === 'ImportDeclaration') {
+            importNodes.push({ start, end });
+            continue;
+        }
+        const name = extractDeclName(node);
+        const kind = mapNodeKind(node);
+        const text = extractLines(content, start, end);
+        chunks.push({
+            id: `${kind}:${name}`,
+            kind,
+            start_line: start,
+            end_line: end,
+            hash: shortHash(text),
+            content: text,
+        });
+    }
+    if (importNodes.length > 0) {
+        const first = importNodes[0].start;
+        const last = importNodes[importNodes.length - 1].end;
+        const text = extractLines(content, first, last);
+        chunks.unshift({
+            id: 'import:_block',
+            kind: 'import',
+            start_line: first,
+            end_line: last,
+            hash: shortHash(text),
+            content: text,
+        });
+    }
+    if (chunks.length === 0)
+        return chunkFixed(content, 100);
+    return chunks;
+}
+function extractDeclName(node) {
+    if (node.type === 'FunctionDeclaration')
+        return node.id?.name ?? 'anonymous';
+    if (node.type === 'ClassDeclaration')
+        return node.id?.name ?? 'anonymous';
+    if (node.type === 'VariableDeclaration') {
+        const d = node.declarations?.[0];
+        return d?.id?.name ?? 'anonymous';
+    }
+    if (node.type === 'ExportNamedDeclaration') {
+        if (node.declaration)
+            return extractDeclName(node.declaration);
+        const first = node.specifiers?.[0];
+        return first?.exported?.name ?? 'named_export';
+    }
+    if (node.type === 'ExportDefaultDeclaration') {
+        if (node.declaration?.id?.name)
+            return node.declaration.id.name;
+        return 'default';
+    }
+    if (node.type === 'TSInterfaceDeclaration')
+        return node.id?.name ?? 'interface';
+    if (node.type === 'TSTypeAliasDeclaration')
+        return node.id?.name ?? 'type';
+    if (node.type === 'TSEnumDeclaration')
+        return node.id?.name ?? 'enum';
+    if (node.type === 'TSModuleDeclaration')
+        return node.id?.name ?? 'module';
+    return node.type;
+}
+function mapNodeKind(node) {
+    const t = node.type;
+    if (t === 'FunctionDeclaration')
+        return 'function';
+    if (t === 'ClassDeclaration')
+        return 'class';
+    if (['VariableDeclaration', 'TSInterfaceDeclaration', 'TSTypeAliasDeclaration', 'TSEnumDeclaration', 'TSModuleDeclaration'].includes(t))
+        return 'variable';
+    if (t === 'ExportNamedDeclaration' || t === 'ExportDefaultDeclaration') {
+        if (node.declaration)
+            return mapNodeKind(node.declaration);
+        return 'variable';
+    }
+    return 'variable';
+}
+// ============================================================
+// Python — indent-based
+// ============================================================
+function chunkPython(content) {
+    const lines = content.split('\n');
+    const chunks = [];
+    let current = null;
+    const pushCurrent = (end) => {
+        if (!current)
+            return;
+        const text = extractLines(content, current.start, end);
+        chunks.push({
+            id: `${current.kind}:${current.name}`,
+            kind: current.kind,
+            start_line: current.start,
+            end_line: end,
+            hash: shortHash(text),
+            content: text,
+        });
+        current = null;
+    };
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.startsWith(' ') || line.startsWith('\t'))
+            continue;
+        const m = line.match(/^(async\s+def|def|class)\s+(\w+)/);
+        if (m) {
+            pushCurrent(i); // previous ends at the line before current
+            const kind = m[1] === 'class' ? 'python_class' : 'python_def';
+            current = { start: i + 1, name: m[2], kind };
+        }
+    }
+    pushCurrent(lines.length);
+    if (chunks.length === 0)
+        return chunkFixed(content, 100);
+    if (chunks[0].start_line > 1) {
+        const preambleText = extractLines(content, 1, chunks[0].start_line - 1);
+        if (preambleText.trim()) {
+            chunks.unshift({
+                id: 'python_preamble',
+                kind: 'python_preamble',
+                start_line: 1,
+                end_line: chunks[0].start_line - 1,
+                hash: shortHash(preambleText),
+                content: preambleText,
+            });
+        }
+    }
+    return chunks;
+}
+// ============================================================
+// Markdown — h2/h3 boundaries
+// ============================================================
+function chunkMarkdown(content) {
+    const lines = content.split('\n');
+    const chunks = [];
+    let current = null;
+    const pushCurrent = (end) => {
+        if (!current)
+            return;
+        const text = extractLines(content, current.start, end);
+        chunks.push({
+            id: `heading:${current.heading}`,
+            kind: 'heading',
+            start_line: current.start,
+            end_line: end,
+            hash: shortHash(text),
+            content: text,
+        });
+        current = null;
+    };
+    for (let i = 0; i < lines.length; i++) {
+        const m = lines[i].match(/^(#{2,3})\s+(.+?)\s*$/);
+        if (m) {
+            pushCurrent(i);
+            current = { start: i + 1, heading: m[2] };
+        }
+    }
+    pushCurrent(lines.length);
+    if (chunks.length === 0)
+        return chunkFixed(content, 100);
+    if (chunks[0].start_line > 1) {
+        const preamble = extractLines(content, 1, chunks[0].start_line - 1);
+        if (preamble.trim()) {
+            chunks.unshift({
+                id: 'heading:_preamble',
+                kind: 'heading',
+                start_line: 1,
+                end_line: chunks[0].start_line - 1,
+                hash: shortHash(preamble),
+                content: preamble,
+            });
+        }
+    }
+    return chunks;
+}
+// ============================================================
+// Fixed — 100-line windows (fallback)
+// ============================================================
+function chunkFixed(content, size) {
+    const lines = content.split('\n');
+    const chunks = [];
+    if (lines.length === 0)
+        return chunks;
+    for (let i = 0; i < lines.length; i += size) {
+        const slice = lines.slice(i, i + size);
+        const text = slice.join('\n');
+        const end = Math.min(i + size, lines.length);
+        chunks.push({
+            id: `lines:${i + 1}_${end}`,
+            kind: 'fixed',
+            start_line: i + 1,
+            end_line: end,
+            hash: shortHash(text),
+            content: text,
+        });
+    }
+    return chunks;
+}
+//# sourceMappingURL=file-chunker.js.map

package/dist/lib/forgetting.d.ts

@@ -0,0 +1,12 @@
+export interface ForgettingInput {
+    daysSinceLastAccess: number;
+    importance: number;
+    heatScore: number;
+    protected: boolean;
+    layer: string;
+}
+export declare function forgettingRisk(input: ForgettingInput): number;
+export declare const COMPRESS_THRESHOLD = 50;
+export declare const DROP_THRESHOLD = 200;
+export type ForgettingAction = 'keep' | 'compress' | 'drop';
+export declare function decideForgetting(input: ForgettingInput): ForgettingAction;

package/dist/lib/forgetting.js

@@ -0,0 +1,31 @@
+// Ported from linksee-app/setup-learning-box.cjs:62-99 (Ebbinghaus forgetting curve).
+// Implements Michie's memory principle 6: active forgetting.
+// Protected memories (caveat layer) and goal layer bypass decay.
+// Returns true if this memory should be forgotten (compressed to summary or deleted).
+// Higher forgettingRisk → more likely to forget.
+export function forgettingRisk(input) {
+    if (input.protected)
+        return 0;
+    if (input.layer === 'goal')
+        return 0; // Goals are WHY-anchors, never auto-forget while active
+    // Original formula from setup-learning-box.cjs:
+    //   daysSinceContact * (heatScore/100) * (1 + daysSinceContact/30)
+    // We INVERT: high heat = low risk (hot memories should be kept).
+    const heatFactor = 1 - (input.heatScore / 100); // 0.0 = keep, 1.0 = drop
+    const importanceFactor = 1 - input.importance;
+    const timeFactor = input.daysSinceLastAccess * (1 + input.daysSinceLastAccess / 30);
+    return heatFactor * importanceFactor * timeFactor;
+}
+// Risk threshold above which memory is compressed (→ learning layer summary) and the original deleted.
+export const COMPRESS_THRESHOLD = 50;
+// Risk threshold above which memory is entirely dropped.
+export const DROP_THRESHOLD = 200;
+export function decideForgetting(input) {
+    const risk = forgettingRisk(input);
+    if (risk >= DROP_THRESHOLD)
+        return 'drop';
+    if (risk >= COMPRESS_THRESHOLD)
+        return 'compress';
+    return 'keep';
+}
+//# sourceMappingURL=forgetting.js.map

package/dist/lib/heat-index.d.ts

@@ -0,0 +1,13 @@
+export type HeatBand = 'hot' | 'warm' | 'cold' | 'frozen';
+export interface HeatInput {
+    accessesLast30d: number;
+    accessesLast90d: number;
+    daysSinceLastAccess: number;
+    totalAccesses: number;
+    baseImportance?: number;
+}
+export interface HeatResult {
+    score: number;
+    band: HeatBand;
+}
+export declare function computeHeat(input: HeatInput): HeatResult;