@astrocyteai/local 0.1.0

package/dist/curated-retain.js

@@ -0,0 +1,118 @@
+/**
+ * LLM-curated retain for local Context Tree.
+ *
+ * When an LLM provider is available, the LLM decides:
+ * - What action to take: ADD, UPDATE, MERGE, SKIP, DELETE
+ * - Which domain to store in (instead of just using the first tag)
+ * - What memory_layer to assign (fact, observation, model)
+ *
+ * Falls back to simple mechanical retain when no LLM is configured.
+ */
+const CURATION_PROMPT = `You are a memory curation agent for a local Context Tree. Analyze the new content and decide how to store it.
+
+## Existing memories (most similar):
+{existing}
+
+## Context Tree domains currently in use:
+{domains}
+
+## New content:
+{content}
+
+## Decide:
+1. action: "add" (new info), "update" (replace existing), "merge" (combine with existing), "skip" (redundant), "delete" (contradicts old)
+2. domain: Which Context Tree directory to store in (e.g., "preferences", "architecture", "decisions"). Use an existing domain if appropriate, or suggest a new one.
+3. memory_layer: "fact" (raw info), "observation" (pattern/insight), "model" (consolidated understanding)
+4. content: The processed text to store (may rewrite for clarity)
+5. reasoning: Brief explanation
+
+Respond with JSON:
+{"action": "add", "domain": "preferences", "content": "...", "memory_layer": "fact", "reasoning": "...", "target_id": null}`;
+export async function curateLocalRetain(options) {
+    const { content, bankId, tree, search, llmProvider, contextLimit = 5 } = options;
+    // Get existing similar memories for context
+    const existingHits = search.search(content, bankId, { limit: contextLimit });
+    let existingText;
+    if (existingHits.length > 0) {
+        existingText = existingHits
+            .map((h) => `- [${h.id}] (${h.domain}/${h.file_path}) score=${h.score.toFixed(2)}: ${h.text.slice(0, 200)}`)
+            .join("\n");
+    }
+    else {
+        existingText = "(no existing memories)";
+    }
+    // Get current domains
+    const domains = tree.listDomains(bankId);
+    const domainsText = domains.length > 0 ? domains.join(", ") : "(none yet)";
+    const prompt = CURATION_PROMPT.replace("{existing}", existingText)
+        .replace("{domains}", domainsText)
+        .replace("{content}", content);
+    try {
+        const completion = await llmProvider.complete({
+            messages: [{ role: "user", content: prompt }],
+            maxTokens: 500,
+            temperature: 0,
+        });
+        return parseResponse(completion.text, content);
+    }
+    catch {
+        return {
+            action: "add",
+            domain: "general",
+            content,
+            memory_layer: "fact",
+            reasoning: "LLM curation failed, defaulting to ADD",
+        };
+    }
+}
+export function parseResponse(response, originalContent) {
+    try {
+        let text = response.trim();
+        // Extract from code block if present
+        if (text.includes("```")) {
+            const start = text.indexOf("```") + 3;
+            let contentStart = start;
+            if (text.slice(start).startsWith("json")) {
+                contentStart = start + 4;
+            }
+            const end = text.indexOf("```", contentStart);
+            if (end > contentStart) {
+                text = text.slice(contentStart, end).trim();
+            }
+        }
+        const data = JSON.parse(text);
+        if (typeof data !== "object" || data === null) {
+            throw new Error("Expected JSON object");
+        }
+        let action = (data.action || "add").toLowerCase();
+        if (!["add", "update", "merge", "skip", "delete"].includes(action)) {
+            action = "add";
+        }
+        let memoryLayer = (data.memory_layer || "fact").toLowerCase();
+        if (!["fact", "observation", "model"].includes(memoryLayer)) {
+            memoryLayer = "fact";
+        }
+        // Sanitize domain name
+        let domain = (data.domain || "general").toLowerCase().trim();
+        domain = domain.replace(/ /g, "-").replace(/\//g, "-");
+        if (!domain)
+            domain = "general";
+        return {
+            action: action,
+            domain,
+            content: data.content || originalContent,
+            memory_layer: memoryLayer,
+            reasoning: data.reasoning || "",
+            target_id: data.target_id || undefined,
+        };
+    }
+    catch {
+        return {
+            action: "add",
+            domain: "general",
+            content: originalContent,
+            memory_layer: "fact",
+            reasoning: "Failed to parse LLM response",
+        };
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @astrocyteai/local — Zero-infrastructure memory for AI coding agents.
+ *
+ * Context Tree + SQLite FTS5 search. No database, no embeddings, no API keys.
+ */
+export { ContextTree } from "./context-tree.js";
+export { SearchEngine } from "./search.js";
+export { createMcpServer, startMcpServer } from "./mcp-server.js";
+export type { McpServerOptions } from "./mcp-server.js";
+export { curateLocalRetain, parseResponse } from "./curated-retain.js";
+export type { LLMProvider, CurationDecision } from "./curated-retain.js";
+export { LocalRecallCache, LocalTieredRetriever } from "./tiered-retrieval.js";
+export type { MemoryEntry, SearchHit, RetainResult, RecallResult, BrowseResult, LocalConfig, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,10 @@
+/**
+ * @astrocyteai/local — Zero-infrastructure memory for AI coding agents.
+ *
+ * Context Tree + SQLite FTS5 search. No database, no embeddings, no API keys.
+ */
+export { ContextTree } from "./context-tree.js";
+export { SearchEngine } from "./search.js";
+export { createMcpServer, startMcpServer } from "./mcp-server.js";
+export { curateLocalRetain, parseResponse } from "./curated-retain.js";
+export { LocalRecallCache, LocalTieredRetriever } from "./tiered-retrieval.js";

package/dist/mcp-server.d.ts

@@ -0,0 +1,18 @@
+/**
+ * MCP server — exposes Context Tree as MCP tools.
+ *
+ * See docs/mcp-tools.md for tool schemas.
+ *
+ * Usage:
+ *   npx @astrocyteai/local --root .astrocyte
+ *   astrocyte-local-mcp --root .astrocyte
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export interface McpServerOptions {
+    root: string;
+    defaultBank?: string;
+    transport?: "stdio" | "sse";
+    port?: number;
+}
+export declare function createMcpServer(options: McpServerOptions): McpServer;
+export declare function startMcpServer(options: McpServerOptions): Promise<void>;

package/dist/mcp-server.js

@@ -0,0 +1,212 @@
+/**
+ * MCP server — exposes Context Tree as MCP tools.
+ *
+ * See docs/mcp-tools.md for tool schemas.
+ *
+ * Usage:
+ *   npx @astrocyteai/local --root .astrocyte
+ *   astrocyte-local-mcp --root .astrocyte
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { ContextTree } from "./context-tree.js";
+import { SearchEngine } from "./search.js";
+export function createMcpServer(options) {
+    const { root, defaultBank = "project" } = options;
+    const tree = new ContextTree(root);
+    const search = new SearchEngine(`${root}/_search.db`);
+    search.buildIndex(tree);
+    const server = new McpServer({
+        name: "astrocyte-local",
+        version: "0.1.0",
+    }, {
+        instructions: "Local memory server. Use memory_retain to store information, " +
+            "memory_recall to search memories, memory_browse to explore the " +
+            "Context Tree hierarchy, and memory_forget to remove memories.",
+    });
+    // ── memory_retain ──
+    server.tool("memory_retain", "Store content into local memory.", {
+        content: z.string().describe("The text to memorize."),
+        bank_id: z.string().optional().describe("Memory bank (default: project)."),
+        tags: z.array(z.string()).optional().describe("Optional tags for filtering."),
+        domain: z.string().optional().describe("Context Tree domain (auto-inferred if omitted)."),
+    }, async (args) => {
+        const bankId = args.bank_id || defaultBank;
+        const domain = args.domain || (args.tags?.[0] ?? "general");
+        const entry = tree.store({
+            content: args.content,
+            bank_id: bankId,
+            domain,
+            tags: args.tags || [],
+        });
+        search.addDocument(entry);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        stored: true,
+                        memory_id: entry.id,
+                        domain: entry.domain,
+                        file: entry.file_path,
+                    }),
+                },
+            ],
+        };
+    });
+    // ── memory_recall ──
+    server.tool("memory_recall", "Search local memory for content relevant to a query.", {
+        query: z.string().describe("Natural language search query."),
+        bank_id: z.string().optional().describe("Memory bank (default: project)."),
+        max_results: z.number().optional().describe("Maximum results (default: 10)."),
+        tags: z.array(z.string()).optional().describe("Filter by tags."),
+    }, async (args) => {
+        const bankId = args.bank_id || defaultBank;
+        const hits = search.search(args.query, bankId, {
+            limit: args.max_results || 10,
+            tags: args.tags,
+        });
+        // Record recall
+        for (const h of hits) {
+            tree.recordRecall(h.id);
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        hits: hits.map((h) => ({
+                            text: h.text,
+                            score: Math.round(h.score * 10000) / 10000,
+                            domain: h.domain,
+                            file: h.file_path,
+                            memory_id: h.id,
+                        })),
+                        total: hits.length,
+                    }),
+                },
+            ],
+        };
+    });
+    // ── memory_browse ──
+    server.tool("memory_browse", "Browse the Context Tree hierarchy.", {
+        path: z.string().optional().describe("Path to browse (empty for root, 'preferences' for a domain)."),
+        bank_id: z.string().optional().describe("Memory bank (default: project)."),
+    }, async (args) => {
+        const bankId = args.bank_id || defaultBank;
+        const browsePath = args.path || "";
+        if (!browsePath) {
+            const domains = tree.listDomains(bankId);
+            const total = tree.count(bankId);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            path: "",
+                            domains,
+                            entries: [],
+                            total_memories: total,
+                        }),
+                    },
+                ],
+            };
+        }
+        const entries = tree.listEntries(bankId, browsePath);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        path: browsePath,
+                        domains: [],
+                        entries: entries.map((e) => ({
+                            file: e.file_path,
+                            title: e.text.slice(0, 80),
+                            memory_id: e.id,
+                            recall_count: e.recall_count,
+                        })),
+                        total_memories: entries.length,
+                    }),
+                },
+            ],
+        };
+    });
+    // ── memory_forget ──
+    server.tool("memory_forget", "Remove memories from local storage.", {
+        memory_ids: z.array(z.string()).describe("IDs of memories to delete."),
+        bank_id: z.string().optional().describe("Memory bank (default: project)."),
+    }, async (args) => {
+        let deleted = 0;
+        const filesRemoved = [];
+        for (const mid of args.memory_ids) {
+            const entry = tree.read(mid);
+            if (entry) {
+                filesRemoved.push(entry.file_path);
+            }
+            if (tree.delete(mid)) {
+                search.removeDocument(mid);
+                deleted++;
+            }
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        deleted_count: deleted,
+                        files_removed: filesRemoved,
+                    }),
+                },
+            ],
+        };
+    });
+    // ── memory_banks ──
+    server.tool("memory_banks", "List available memory banks.", {}, async () => {
+        const allEntries = tree.scanAll();
+        const bankIds = [...new Set(allEntries.map((e) => e.bank_id))].sort();
+        if (!bankIds.includes(defaultBank)) {
+            bankIds.unshift(defaultBank);
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        banks: bankIds,
+                        default: defaultBank,
+                        root,
+                    }),
+                },
+            ],
+        };
+    });
+    // ── memory_health ──
+    server.tool("memory_health", "Check local memory system health.", {}, async () => {
+        const total = tree.count();
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        healthy: true,
+                        total_memories: total,
+                        index_status: "current",
+                        root,
+                    }),
+                },
+            ],
+        };
+    });
+    return server;
+}
+export async function startMcpServer(options) {
+    const server = createMcpServer(options);
+    if (options.transport === "sse") {
+        // SSE transport would require express — for now only stdio
+        throw new Error("SSE transport not yet implemented in TypeScript. Use stdio.");
+    }
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}

package/dist/search.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Search engine — SQLite FTS5 full-text search.
+ *
+ * See docs/search-contract.md for behavior specification.
+ * All operations are sync. Uses better-sqlite3 for SQLite access.
+ */
+import type { MemoryEntry, SearchHit } from "./types.js";
+import type { ContextTree } from "./context-tree.js";
+export declare class SearchEngine {
+    private dbPath;
+    private db;
+    constructor(dbPath: string);
+    private createTables;
+    /**
+     * Rebuild the FTS index from the Context Tree. Returns count indexed.
+     */
+    buildIndex(tree: ContextTree, bankId?: string): number;
+    /**
+     * Full-text search. Returns scored hits sorted by relevance.
+     */
+    search(query: string, bankId: string, options?: {
+        limit?: number;
+        tags?: string[];
+        layers?: string[];
+    }): SearchHit[];
+    /**
+     * Add a single entry to the index (incremental update).
+     */
+    addDocument(entry: MemoryEntry): void;
+    /**
+     * Remove a single entry from the index.
+     */
+    removeDocument(entryId: string): void;
+    /**
+     * Close the database connection.
+     */
+    close(): void;
+    private searchAll;
+    private rowsToHits;
+    /**
+     * Escape special FTS5 characters for safe querying.
+     * Does NOT quote individual tokens — quoting disables stemming.
+     */
+    static escapeFtsQuery(query: string): string;
+}

package/dist/search.js

@@ -0,0 +1,174 @@
+/**
+ * Search engine — SQLite FTS5 full-text search.
+ *
+ * See docs/search-contract.md for behavior specification.
+ * All operations are sync. Uses better-sqlite3 for SQLite access.
+ */
+import Database from "better-sqlite3";
+import path from "node:path";
+import fs from "node:fs";
+export class SearchEngine {
+    dbPath;
+    db;
+    constructor(dbPath) {
+        this.dbPath = dbPath;
+        const dir = path.dirname(dbPath);
+        fs.mkdirSync(dir, { recursive: true });
+        this.db = new Database(dbPath);
+        this.db.pragma("journal_mode = WAL");
+        this.createTables();
+    }
+    createTables() {
+        this.db.exec(`
+      CREATE VIRTUAL TABLE IF NOT EXISTS memory_fts USING fts5(
+        id,
+        bank_id,
+        text,
+        tags,
+        domain,
+        memory_layer,
+        fact_type,
+        file_path,
+        tokenize='porter unicode61'
+      );
+    `);
+    }
+    /**
+     * Rebuild the FTS index from the Context Tree. Returns count indexed.
+     */
+    buildIndex(tree, bankId) {
+        if (bankId) {
+            this.db.prepare("DELETE FROM memory_fts WHERE bank_id = ?").run(bankId);
+        }
+        else {
+            this.db.exec("DELETE FROM memory_fts");
+        }
+        const entries = tree.scanAll(bankId);
+        const insert = this.db.prepare(`INSERT INTO memory_fts (id, bank_id, text, tags, domain, memory_layer, fact_type, file_path)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`);
+        const insertMany = this.db.transaction((entries) => {
+            for (const entry of entries) {
+                insert.run(entry.id, entry.bank_id, entry.text, entry.tags.join(" "), entry.domain, entry.memory_layer, entry.fact_type, entry.file_path);
+            }
+        });
+        insertMany(entries);
+        return entries.length;
+    }
+    /**
+     * Full-text search. Returns scored hits sorted by relevance.
+     */
+    search(query, bankId, options) {
+        const limit = options?.limit ?? 10;
+        const tags = options?.tags;
+        const layers = options?.layers;
+        if (query.trim() === "*") {
+            return this.searchAll(bankId, { limit, tags, layers });
+        }
+        const ftsQuery = SearchEngine.escapeFtsQuery(query);
+        if (!ftsQuery)
+            return [];
+        let rows;
+        try {
+            rows = this.db
+                .prepare(`SELECT id, bank_id, text, tags, domain, memory_layer, fact_type, file_path, rank
+           FROM memory_fts
+           WHERE memory_fts MATCH ? AND bank_id = ?
+           ORDER BY rank
+           LIMIT ?`)
+                .all(ftsQuery, bankId, limit * 3);
+        }
+        catch {
+            return [];
+        }
+        let hits = this.rowsToHits(rows);
+        // Post-filter by tags
+        if (tags && tags.length > 0) {
+            const tagSet = new Set(tags);
+            hits = hits.filter((h) => h.tags && tagSet.size > 0 && [...tagSet].every((t) => h.tags.includes(t)));
+        }
+        // Post-filter by layers
+        if (layers && layers.length > 0) {
+            hits = hits.filter((h) => h.memory_layer && layers.includes(h.memory_layer));
+        }
+        return hits.slice(0, limit);
+    }
+    /**
+     * Add a single entry to the index (incremental update).
+     */
+    addDocument(entry) {
+        this.db
+            .prepare(`INSERT INTO memory_fts (id, bank_id, text, tags, domain, memory_layer, fact_type, file_path)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(entry.id, entry.bank_id, entry.text, entry.tags.join(" "), entry.domain, entry.memory_layer, entry.fact_type, entry.file_path);
+    }
+    /**
+     * Remove a single entry from the index.
+     */
+    removeDocument(entryId) {
+        this.db.prepare("DELETE FROM memory_fts WHERE id = ?").run(entryId);
+    }
+    /**
+     * Close the database connection.
+     */
+    close() {
+        this.db.close();
+    }
+    // ── Internal ──
+    searchAll(bankId, options) {
+        const rows = this.db
+            .prepare(`SELECT id, bank_id, text, tags, domain, memory_layer, fact_type, file_path, 0 as rank
+         FROM memory_fts WHERE bank_id = ? LIMIT ?`)
+            .all(bankId, options.limit);
+        let hits = this.rowsToHits(rows, 1.0);
+        if (options.tags && options.tags.length > 0) {
+            const tagSet = new Set(options.tags);
+            hits = hits.filter((h) => h.tags && [...tagSet].every((t) => h.tags.includes(t)));
+        }
+        if (options.layers && options.layers.length > 0) {
+            hits = hits.filter((h) => h.memory_layer && options.layers.includes(h.memory_layer));
+        }
+        return hits;
+    }
+    rowsToHits(rows, defaultScore) {
+        if (rows.length === 0)
+            return [];
+        // Normalize BM25 scores (more negative = more relevant)
+        const rawScores = rows.map((r) => Math.abs(Number(r.rank)));
+        const maxScore = Math.max(...rawScores) || 1.0;
+        return rows.map((row) => {
+            const score = defaultScore !== undefined
+                ? defaultScore
+                : maxScore > 0
+                    ? Math.abs(Number(row.rank)) / maxScore
+                    : 0.5;
+            const tagStr = row.tags || "";
+            const tags = tagStr.split(/\s+/).filter(Boolean);
+            return {
+                id: row.id,
+                text: row.text,
+                score,
+                bank_id: row.bank_id,
+                domain: row.domain,
+                file_path: row.file_path,
+                memory_layer: row.memory_layer || undefined,
+                fact_type: row.fact_type || undefined,
+                tags,
+            };
+        });
+    }
+    /**
+     * Escape special FTS5 characters for safe querying.
+     * Does NOT quote individual tokens — quoting disables stemming.
+     */
+    static escapeFtsQuery(query) {
+        let cleaned = query
+            .replace(/"/g, " ")
+            .replace(/'/g, " ")
+            .replace(/\(/g, " ")
+            .replace(/\)/g, " ")
+            .replace(/:/g, " ")
+            .replace(/\^/g, " ");
+        const tokens = cleaned.split(/\s+/).filter(Boolean);
+        return tokens.join(" ");
+    }
+}

package/dist/tiered-retrieval.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Tiered retrieval for local Context Tree — cache → FTS5 → LLM-guided.
+ *
+ * 3-tier progressive escalation adapted for file-based storage:
+ *   Tier 0: In-memory result cache (exact/fuzzy query match)
+ *   Tier 1: FTS5 keyword search (standard)
+ *   Tier 2: LLM-guided query reformulation + FTS5 retry
+ *
+ * Stops when sufficient results are found. No embeddings needed.
+ */
+import type { SearchHit } from "./types.js";
+import type { SearchEngine } from "./search.js";
+import type { LLMProvider } from "./curated-retain.js";
+export declare class LocalRecallCache {
+    private maxEntries;
+    private ttlMs;
+    private cache;
+    constructor(maxEntries?: number, ttlMs?: number);
+    get(query: string, bankId: string): SearchHit[] | null;
+    put(query: string, bankId: string, hits: SearchHit[]): void;
+    invalidateBank(bankId: string): void;
+    invalidateAll(): void;
+    size(): number;
+}
+export declare class LocalTieredRetriever {
+    private search;
+    private cache;
+    private llmProvider;
+    private minResults;
+    private minScore;
+    readonly maxTier: number;
+    constructor(search: SearchEngine, cache?: LocalRecallCache | null, llmProvider?: LLMProvider | null, minResults?: number, minScore?: number, maxTier?: number);
+    /**
+     * Run tiered retrieval. Returns [hits, tierUsed].
+     */
+    retrieve(query: string, bankId: string, options?: {
+        limit?: number;
+        tags?: string[];
+    }): [SearchHit[], number];
+    /**
+     * Async version of retrieve — supports LLM reformulation natively.
+     */
+    aretrieve(query: string, bankId: string, options?: {
+        limit?: number;
+        tags?: string[];
+    }): Promise<[SearchHit[], number]>;
+    private sufficient;
+    private reformulate;
+    /**
+     * Merge two hit lists, deduplicate by ID, keep highest score.
+     */
+    static mergeHits(hitsA: SearchHit[], hitsB: SearchHit[]): SearchHit[];
+}