linksee-memory 0.2.0 → 0.4.0

package/dist/mcp/resources.js

@@ -0,0 +1,162 @@
+// Resources block — expose memories as URI-addressable resources.
+//
+// Static resources (always present):
+//   memory://stats       — DB statistics summary
+//   memory://hot         — currently hot memories (top heat band)
+//   memory://recent      — recently accessed memories (last 7 days)
+//   memory://caveats     — all caveat-layer memories (the never-forget pile)
+//
+// Resource templates (parameterized):
+//   memory://entity/{name}  — all memories for an entity
+//   memory://layer/{layer}  — all memories in a layer (goal/context/emotion/implementation/caveat/learning)
+//   memory://memory/{id}    — single memory by ID
+export const STATIC_RESOURCES = [
+    {
+        uri: 'memory://stats',
+        name: 'Memory store statistics',
+        description: 'Summary counts: entities, memories, layer breakdown, heat distribution.',
+        mimeType: 'application/json',
+    },
+    {
+        uri: 'memory://hot',
+        name: 'Hot memories',
+        description: 'Memories currently in the "hot" heat band — what the agent is actively working with.',
+        mimeType: 'application/json',
+    },
+    {
+        uri: 'memory://recent',
+        name: 'Recently accessed memories',
+        description: 'Memories accessed in the last 7 days, ordered by recency.',
+        mimeType: 'application/json',
+    },
+    {
+        uri: 'memory://caveats',
+        name: 'All caveats',
+        description: 'Every caveat-layer memory — the protected "never forget" pile of pain lessons.',
+        mimeType: 'application/json',
+    },
+];
+export const RESOURCE_TEMPLATES = [
+    {
+        uriTemplate: 'memory://entity/{name}',
+        name: 'Memories for an entity',
+        description: 'All memories about a specific entity (person/company/project/concept/file). Replace {name} with the entity name.',
+        mimeType: 'application/json',
+    },
+    {
+        uriTemplate: 'memory://layer/{layer}',
+        name: 'Memories in a layer',
+        description: 'All memories in a specific layer. Replace {layer} with one of: goal, context, emotion, implementation, caveat, learning.',
+        mimeType: 'application/json',
+    },
+    {
+        uriTemplate: 'memory://memory/{id}',
+        name: 'A single memory',
+        description: 'Read a single memory by its numeric id. Replace {id} with the memory_id.',
+        mimeType: 'application/json',
+    },
+];
+const VALID_LAYERS = new Set(['goal', 'context', 'emotion', 'implementation', 'caveat', 'learning']);
+function fmtMemory(row) {
+    return {
+        id: row.id,
+        entity: row.entity_name,
+        entity_kind: row.entity_kind,
+        layer: row.layer,
+        importance: row.importance,
+        pinned: row.protected === 1 || row.importance >= 0.9,
+        content: row.content,
+        created_at: row.created_at ? new Date(row.created_at * 1000).toISOString() : null,
+        last_accessed_at: row.last_accessed_at ? new Date(row.last_accessed_at * 1000).toISOString() : null,
+        access_count: row.access_count,
+    };
+}
+const SELECT_MEMORY_BASE = `
+  SELECT m.id, m.layer, m.content, m.importance, m.protected, m.created_at, m.last_accessed_at, m.access_count,
+         e.name as entity_name, e.kind as entity_kind
+  FROM memories m JOIN entities e ON e.id = m.entity_id
+`;
+export function readResource(db, uri) {
+    // Static endpoints
+    if (uri === 'memory://stats') {
+        const entityCount = db.prepare('SELECT COUNT(*) as c FROM entities').get().c;
+        const memCount = db.prepare('SELECT COUNT(*) as c FROM memories').get().c;
+        const byLayer = db.prepare('SELECT layer, COUNT(*) as c FROM memories GROUP BY layer').all();
+        const byKind = db.prepare('SELECT kind, COUNT(*) as c FROM entities GROUP BY kind').all();
+        const pinned = db.prepare('SELECT COUNT(*) as c FROM memories WHERE importance >= 0.9 OR protected = 1').get().c;
+        return {
+            uri,
+            mimeType: 'application/json',
+            text: JSON.stringify({
+                entity_count: entityCount,
+                memory_count: memCount,
+                pinned_count: pinned,
+                by_layer: Object.fromEntries(byLayer.map((r) => [r.layer, r.c])),
+                by_entity_kind: Object.fromEntries(byKind.map((r) => [r.kind, r.c])),
+                // Note: heat_band is computed at recall-time, not stored — see recall tool for live heat.
+            }, null, 2),
+        };
+    }
+    if (uri === 'memory://hot') {
+        // heat_band is dynamic; approximate "hot" via access_count + recent access desc.
+        // For exact heat scoring, use the recall tool with band='hot'.
+        const rows = db
+            .prepare(`${SELECT_MEMORY_BASE}
+         WHERE m.last_accessed_at IS NOT NULL
+         ORDER BY m.access_count DESC, m.last_accessed_at DESC
+         LIMIT 50`)
+            .all();
+        return {
+            uri,
+            mimeType: 'application/json',
+            text: JSON.stringify({ count: rows.length, note: 'Approximation by access_count + last_accessed_at. Use the recall tool with band="hot" for exact heat scoring.', memories: rows.map(fmtMemory) }, null, 2),
+        };
+    }
+    if (uri === 'memory://recent') {
+        const cutoff = Math.floor(Date.now() / 1000) - 7 * 24 * 3600;
+        const rows = db.prepare(`${SELECT_MEMORY_BASE} WHERE m.last_accessed_at >= ? ORDER BY m.last_accessed_at DESC LIMIT 50`).all(cutoff);
+        return { uri, mimeType: 'application/json', text: JSON.stringify({ count: rows.length, memories: rows.map(fmtMemory) }, null, 2) };
+    }
+    if (uri === 'memory://caveats') {
+        const rows = db.prepare(`${SELECT_MEMORY_BASE} WHERE m.layer = 'caveat' ORDER BY m.importance DESC, m.created_at DESC`).all();
+        return { uri, mimeType: 'application/json', text: JSON.stringify({ count: rows.length, memories: rows.map(fmtMemory) }, null, 2) };
+    }
+    // Templates
+    const entityMatch = uri.match(/^memory:\/\/entity\/(.+)$/);
+    if (entityMatch) {
+        const name = decodeURIComponent(entityMatch[1]);
+        const rows = db
+            .prepare(`${SELECT_MEMORY_BASE} WHERE LOWER(e.name) = LOWER(?) ORDER BY m.importance DESC, m.created_at DESC`)
+            .all(name);
+        return {
+            uri,
+            mimeType: 'application/json',
+            text: JSON.stringify({ entity: name, count: rows.length, memories: rows.map(fmtMemory) }, null, 2),
+        };
+    }
+    const layerMatch = uri.match(/^memory:\/\/layer\/(.+)$/);
+    if (layerMatch) {
+        const layer = decodeURIComponent(layerMatch[1]).toLowerCase();
+        if (!VALID_LAYERS.has(layer)) {
+            throw new Error(`unknown layer "${layer}". Known: goal, context, emotion, implementation, caveat, learning`);
+        }
+        const rows = db
+            .prepare(`${SELECT_MEMORY_BASE} WHERE m.layer = ? ORDER BY m.importance DESC, m.created_at DESC LIMIT 200`)
+            .all(layer);
+        return {
+            uri,
+            mimeType: 'application/json',
+            text: JSON.stringify({ layer, count: rows.length, memories: rows.map(fmtMemory) }, null, 2),
+        };
+    }
+    const idMatch = uri.match(/^memory:\/\/memory\/(\d+)$/);
+    if (idMatch) {
+        const id = Number(idMatch[1]);
+        const row = db.prepare(`${SELECT_MEMORY_BASE} WHERE m.id = ?`).get(id);
+        if (!row)
+            throw new Error(`memory id ${id} not found`);
+        return { uri, mimeType: 'application/json', text: JSON.stringify(fmtMemory(row), null, 2) };
+    }
+    throw new Error(`unknown resource URI: ${uri}`);
+}
+//# sourceMappingURL=resources.js.map

package/dist/mcp/roots.d.ts

@@ -0,0 +1,10 @@
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+interface Root {
+    uri: string;
+    name?: string;
+}
+export declare function fetchRoots(server: Server): Promise<Root[]>;
+export declare function invalidateRootsCache(): void;
+export declare function rootPathFromUri(uri: string): string;
+export declare function isInsideRoots(filePath: string, roots: Root[]): boolean;
+export {};

package/dist/mcp/roots.js

@@ -0,0 +1,64 @@
+// Roots block — track the client's working roots (directories the agent is operating in).
+//
+// The server pulls roots from the client via server.request({method: 'roots/list'}) and caches them.
+// Used by recall_file and read_smart to bias path-substring matches toward files inside a current root.
+//
+// MCP semantics: client owns the root list, server is informed. We refresh on demand
+// (lazily on first use) and on roots/list_changed notification.
+import { ListRootsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+let cachedRoots = null;
+let lastFetched = 0;
+const STALE_MS = 60_000; // re-fetch at most once a minute
+export async function fetchRoots(server) {
+    const now = Date.now();
+    if (cachedRoots && now - lastFetched < STALE_MS)
+        return cachedRoots;
+    try {
+        const res = await server.request({ method: 'roots/list', params: {} }, ListRootsRequestSchema);
+        cachedRoots = Array.isArray(res?.roots) ? res.roots : [];
+        lastFetched = now;
+    }
+    catch {
+        // Client may not support roots; treat as empty.
+        cachedRoots = [];
+        lastFetched = now;
+    }
+    return cachedRoots ?? [];
+}
+export function invalidateRootsCache() {
+    cachedRoots = null;
+    lastFetched = 0;
+}
+// Convert "file:///C:/Users/HP/foo" → "C:/Users/HP/foo" (or "/Users/foo" on POSIX)
+export function rootPathFromUri(uri) {
+    if (uri.startsWith('file:///')) {
+        let p = uri.slice('file:///'.length);
+        // Windows: convert "C:/Users/..." (already POSIX-ish) — leave as-is, caller normalizes.
+        if (process.platform === 'win32') {
+            // also handle "C%3A/" encoding
+            p = p.replace(/^([A-Za-z])(?:%3A|:)\//, '$1:/');
+        }
+        else {
+            p = '/' + p;
+        }
+        try {
+            return decodeURIComponent(p);
+        }
+        catch {
+            return p;
+        }
+    }
+    return uri;
+}
+// Returns true if filePath is inside any of the roots (case-insensitive on win32).
+export function isInsideRoots(filePath, roots) {
+    if (roots.length === 0)
+        return true; // no roots → no filtering
+    const norm = process.platform === 'win32' ? filePath.toLowerCase().replace(/\\/g, '/') : filePath;
+    return roots.some((r) => {
+        const rp = rootPathFromUri(r.uri);
+        const rpn = process.platform === 'win32' ? rp.toLowerCase().replace(/\\/g, '/') : rp;
+        return norm.startsWith(rpn);
+    });
+}
+//# sourceMappingURL=roots.js.map

package/dist/mcp/sampling.d.ts

@@ -0,0 +1,16 @@
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+interface SampleParams {
+    systemPrompt?: string;
+    userPrompt: string;
+    maxTokens?: number;
+    temperature?: number;
+}
+interface SampleResult {
+    ok: boolean;
+    text?: string;
+    reason?: string;
+}
+export declare function sample(server: Server, p: SampleParams): Promise<SampleResult>;
+export declare function sampleConsolidation(server: Server, memoryTexts: string[], entityName: string): Promise<SampleResult>;
+export declare function sampleLayerClassification(server: Server, content: string): Promise<SampleResult>;
+export {};

package/dist/mcp/sampling.js

@@ -0,0 +1,78 @@
+// Sampling block — server requests text generation from the client's LLM.
+//
+// MCP semantics: server.request({method: 'sampling/createMessage', params: {messages, ...}})
+// Used by:
+//   - LLM-assisted consolidate (auto-summarize a memory cluster into a learning entry)
+//   - LLM-assisted layer classification (when the agent uses a vague layer alias)
+//
+// The client may decline (no LLM access, user opted out). All sampling calls are best-effort
+// with a graceful fallback to non-LLM behavior.
+import { CreateMessageRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+export async function sample(server, p) {
+    try {
+        const params = {
+            messages: [{ role: 'user', content: { type: 'text', text: p.userPrompt } }],
+            maxTokens: p.maxTokens ?? 800,
+            temperature: p.temperature ?? 0.3,
+            modelPreferences: {
+                // Prefer fast, cheap, good-enough for summarization.
+                speedPriority: 0.7,
+                costPriority: 0.7,
+                intelligencePriority: 0.4,
+            },
+            includeContext: 'none',
+        };
+        if (p.systemPrompt)
+            params.systemPrompt = p.systemPrompt;
+        const res = await server.request({ method: 'sampling/createMessage', params }, CreateMessageRequestSchema);
+        const text = res?.content?.text ?? res?.content?.[0]?.text ?? '';
+        if (!text)
+            return { ok: false, reason: 'empty response from sampling' };
+        return { ok: true, text };
+    }
+    catch (err) {
+        return { ok: false, reason: err?.message ?? String(err) };
+    }
+}
+export async function sampleConsolidation(server, memoryTexts, entityName) {
+    if (memoryTexts.length === 0)
+        return { ok: false, reason: 'no input memories' };
+    const numbered = memoryTexts.map((t, i) => `[${i + 1}] ${t}`).join('\n\n');
+    const userPrompt = `Consolidate these ${memoryTexts.length} memories about "${entityName}" into a single learning-layer summary. The summary must:
+- Preserve the trajectory (what was attempted, what worked, what changed)
+- Be 2-4 sentences max
+- Not invent facts not in the originals
+- Not include verbatim quotes
+
+Memories:
+${numbered}
+
+Output the summary text only — no preamble, no JSON wrapper.`;
+    return sample(server, {
+        systemPrompt: 'You are a memory consolidator. Compress without distorting.',
+        userPrompt,
+        maxTokens: 400,
+        temperature: 0.2,
+    });
+}
+export async function sampleLayerClassification(server, content) {
+    const userPrompt = `Classify this memory content into exactly one layer:
+- goal: WHY this work exists, target outcome
+- context: WHY THIS NOW, situation, timing
+- emotion: USER tone, feelings expressed
+- implementation: HOW it was done, what worked, what failed
+- caveat: PAIN lesson, "never X" / "always Y"
+- learning: GROWTH, decisions made, insights
+
+Content:
+${content}
+
+Output just the layer name — no explanation, no JSON.`;
+    return sample(server, {
+        systemPrompt: 'You are a layer classifier. Output one word.',
+        userPrompt,
+        maxTokens: 16,
+        temperature: 0,
+    });
+}
+//# sourceMappingURL=sampling.js.map