@astrocyteai/local 0.1.0

package/dist/tiered-retrieval.js

@@ -0,0 +1,187 @@
+/**
+ * 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.
+ */
+export class LocalRecallCache {
+    maxEntries;
+    ttlMs;
+    cache = new Map();
+    constructor(maxEntries = 128, ttlMs = 120_000) {
+        this.maxEntries = maxEntries;
+        this.ttlMs = ttlMs;
+    }
+    get(query, bankId) {
+        const key = `${bankId}:${query.toLowerCase().trim()}`;
+        const entry = this.cache.get(key);
+        if (!entry)
+            return null;
+        // Check TTL
+        if (performance.now() - entry.timestamp > this.ttlMs) {
+            this.cache.delete(key);
+            return null;
+        }
+        return entry.hits;
+    }
+    put(query, bankId, hits) {
+        const key = `${bankId}:${query.toLowerCase().trim()}`;
+        // LRU eviction
+        while (this.cache.size >= this.maxEntries) {
+            const oldestKey = this.cache.keys().next().value;
+            this.cache.delete(oldestKey);
+        }
+        this.cache.set(key, {
+            query,
+            bankId,
+            hits,
+            timestamp: performance.now(),
+        });
+    }
+    invalidateBank(bankId) {
+        const prefix = `${bankId}:`;
+        for (const key of [...this.cache.keys()]) {
+            if (key.startsWith(prefix)) {
+                this.cache.delete(key);
+            }
+        }
+    }
+    invalidateAll() {
+        this.cache.clear();
+    }
+    size() {
+        return this.cache.size;
+    }
+}
+// ── Tiered Retriever ──
+export class LocalTieredRetriever {
+    search;
+    cache;
+    llmProvider;
+    minResults;
+    minScore;
+    maxTier;
+    constructor(search, cache = null, llmProvider = null, minResults = 2, minScore = 0.3, maxTier = 1) {
+        this.search = search;
+        this.cache = cache;
+        this.llmProvider = llmProvider;
+        this.minResults = minResults;
+        this.minScore = minScore;
+        this.maxTier = Math.min(maxTier, 2);
+    }
+    /**
+     * Run tiered retrieval. Returns [hits, tierUsed].
+     */
+    retrieve(query, bankId, options) {
+        const limit = options?.limit ?? 10;
+        const tags = options?.tags;
+        // ── Tier 0: Cache ──
+        if (this.cache && this.maxTier >= 0) {
+            const cached = this.cache.get(query, bankId);
+            if (cached !== null) {
+                return [cached.slice(0, limit), 0];
+            }
+        }
+        // ── Tier 1: FTS5 search ──
+        let hits = [];
+        if (this.maxTier >= 1) {
+            hits = this.search.search(query, bankId, { limit, tags });
+            if (this.sufficient(hits) || this.maxTier <= 1) {
+                if (this.cache && hits.length > 0) {
+                    this.cache.put(query, bankId, hits);
+                }
+                return [hits, 1];
+            }
+        }
+        // ── Tier 2: LLM-guided reformulation (sync path — skip if in async context) ──
+        // TypeScript doesn't have asyncio.run() equivalent, so tier 2
+        // is only available via aretrieve(). Cache whatever we have.
+        if (this.cache && hits.length > 0) {
+            this.cache.put(query, bankId, hits);
+        }
+        return [hits.slice(0, limit), Math.max(this.maxTier >= 1 ? 1 : 0, 0)];
+    }
+    /**
+     * Async version of retrieve — supports LLM reformulation natively.
+     */
+    async aretrieve(query, bankId, options) {
+        const limit = options?.limit ?? 10;
+        const tags = options?.tags;
+        // ── Tier 0: Cache ──
+        if (this.cache && this.maxTier >= 0) {
+            const cached = this.cache.get(query, bankId);
+            if (cached !== null) {
+                return [cached.slice(0, limit), 0];
+            }
+        }
+        // ── Tier 1: FTS5 search ──
+        let hits = [];
+        if (this.maxTier >= 1) {
+            hits = this.search.search(query, bankId, { limit, tags });
+            if (this.sufficient(hits) || this.maxTier <= 1) {
+                if (this.cache && hits.length > 0) {
+                    this.cache.put(query, bankId, hits);
+                }
+                return [hits, 1];
+            }
+        }
+        // ── Tier 2: LLM-guided reformulation ──
+        if (this.maxTier >= 2 && this.llmProvider) {
+            const reformulated = await this.reformulate(query);
+            if (reformulated !== query) {
+                const hits2 = this.search.search(reformulated, bankId, { limit, tags });
+                const merged = LocalTieredRetriever.mergeHits(hits, hits2);
+                if (this.cache) {
+                    this.cache.put(query, bankId, merged);
+                }
+                return [merged.slice(0, limit), 2];
+            }
+        }
+        // Cache whatever we have from tier 1
+        if (this.cache && hits.length > 0) {
+            this.cache.put(query, bankId, hits);
+        }
+        return [hits.slice(0, limit), Math.max(this.maxTier, 0)];
+    }
+    sufficient(hits) {
+        if (hits.length < this.minResults)
+            return false;
+        const avgScore = hits.reduce((sum, h) => sum + h.score, 0) / Math.max(hits.length, 1);
+        return avgScore >= this.minScore;
+    }
+    async reformulate(query) {
+        if (!this.llmProvider)
+            return query;
+        const prompt = "Reformulate this search query to improve keyword-based search results. " +
+            "Add synonyms and related terms. Return only the reformulated query.\n\n" +
+            `Query: ${query}`;
+        try {
+            const completion = await this.llmProvider.complete({
+                messages: [{ role: "user", content: prompt }],
+                maxTokens: 100,
+                temperature: 0.3,
+            });
+            return completion.text.trim() || query;
+        }
+        catch {
+            return query;
+        }
+    }
+    /**
+     * Merge two hit lists, deduplicate by ID, keep highest score.
+     */
+    static mergeHits(hitsA, hitsB) {
+        const best = new Map();
+        for (const h of [...hitsA, ...hitsB]) {
+            const prev = best.get(h.id);
+            if (!prev || h.score > prev.score) {
+                best.set(h.id, h);
+            }
+        }
+        return [...best.values()].sort((a, b) => b.score - a.score);
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Shared types for astrocyte-local.
+ * Matches the Context Tree format spec in docs/context-tree-format.md.
+ */
+export interface MemoryEntry {
+    id: string;
+    bank_id: string;
+    text: string;
+    domain: string;
+    file_path: string;
+    memory_layer: "fact" | "observation" | "model";
+    fact_type: "world" | "experience" | "observation";
+    tags: string[];
+    created_at: string;
+    updated_at: string;
+    occurred_at?: string;
+    recall_count: number;
+    last_recalled_at?: string;
+    source?: string;
+    metadata: Record<string, string | number | boolean | null>;
+}
+export interface SearchHit {
+    id: string;
+    text: string;
+    score: number;
+    bank_id: string;
+    domain: string;
+    file_path: string;
+    memory_layer?: string;
+    fact_type?: string;
+    tags: string[];
+    occurred_at?: string;
+    metadata?: Record<string, string | number | boolean | null>;
+}
+export interface RetainResult {
+    stored: boolean;
+    memory_id: string;
+    domain: string;
+    file: string;
+    error?: string;
+}
+export interface RecallResult {
+    hits: SearchHit[];
+    total: number;
+}
+export interface BrowseResult {
+    path: string;
+    domains: string[];
+    entries: Array<{
+        file: string;
+        title: string;
+        memory_id: string;
+        recall_count: number;
+    }>;
+    total_memories: number;
+}
+export interface LocalConfig {
+    default_bank_id: string;
+    expose_reflect: boolean;
+    expose_forget: boolean;
+    root: string;
+}

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * Shared types for astrocyte-local.
+ * Matches the Context Tree format spec in docs/context-tree-format.md.
+ */
+export {};

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@astrocyteai/local",
+  "version": "0.1.0",
+  "description": "Zero-infrastructure memory for AI coding agents — Context Tree + FTS5 search",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "astrocyte-local": "dist/cli.js",
+    "astrocyte-local-mcp": "dist/mcp-server.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest",
+    "lint": "eslint src/",
+    "mcp": "tsx src/mcp-server.ts"
+  },
+  "keywords": [
+    "astrocyte",
+    "memory",
+    "mcp",
+    "ai-agent",
+    "context-tree"
+  ],
+  "author": "AstrocyteAI",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AstrocyteAI/astrocyte-local"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "better-sqlite3": "^11.0.0",
+    "commander": "^13.0.0",
+    "yaml": "^2.4.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.0",
+    "@types/node": "^22.0.0",
+    "eslint": "^9.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "better-sqlite3"
+    ]
+  }
+}

package/src/cli.ts

@@ -0,0 +1,304 @@
+#!/usr/bin/env node
+
+/**
+ * CLI for Astrocyte Local — retain, search, browse, forget, export.
+ *
+ * See docs/cli-reference.md for the full command specification.
+ *
+ * Usage:
+ *   astrocyte-local retain "Calvin prefers dark mode" --tags preference
+ *   astrocyte-local search "dark mode"
+ *   astrocyte-local browse
+ *   astrocyte-local forget a1b2c3d4e5f6
+ *   astrocyte-local export --output backup.ama.jsonl
+ *   astrocyte-local health
+ *   astrocyte-local mcp
+ */
+
+import { Command } from "commander";
+import path from "node:path";
+import fs from "node:fs";
+import { ContextTree } from "./context-tree.js";
+import { SearchEngine } from "./search.js";
+import { startMcpServer } from "./mcp-server.js";
+
+const program = new Command();
+
+program
+  .name("astrocyte-local")
+  .description("Local memory for AI coding agents")
+  .version("0.1.0")
+  .option("-r, --root <path>", "Context Tree root directory", ".astrocyte")
+  .option("-b, --bank <id>", "Memory bank ID", "project")
+  .option("-f, --format <fmt>", "Output format (text|json)", "text");
+
+// ── retain ──
+
+program
+  .command("retain")
+  .description("Store content into memory")
+  .argument("[content]", "Content to retain")
+  .option("--tags <tags>", "Comma-separated tags")
+  .option("--domain <domain>", "Context Tree domain")
+  .option("--stdin", "Read from stdin")
+  .action(async (content: string | undefined, opts: Record<string, string | boolean>) => {
+    const globals = program.opts();
+    const tree = new ContextTree(globals.root);
+    const search = new SearchEngine(path.join(globals.root, "_search.db"));
+
+    let text = content;
+    if (opts.stdin || !text) {
+      const chunks: Buffer[] = [];
+      for await (const chunk of process.stdin) {
+        chunks.push(chunk);
+      }
+      text = Buffer.concat(chunks).toString("utf-8").trim();
+    }
+    if (!text) {
+      console.error("Error: no content provided");
+      process.exit(2);
+    }
+
+    const tags = opts.tags ? (opts.tags as string).split(",").map((t: string) => t.trim()) : [];
+    const domain = (opts.domain as string) || (tags[0] || "general");
+
+    const entry = tree.store({
+      content: text,
+      bank_id: globals.bank,
+      domain,
+      tags,
+    });
+    search.addDocument(entry);
+    search.close();
+
+    if (globals.format === "json") {
+      console.log(
+        JSON.stringify({
+          stored: true,
+          memory_id: entry.id,
+          domain: entry.domain,
+          file: entry.file_path,
+        })
+      );
+    } else {
+      console.log(`Stored: ${entry.id} → ${entry.file_path}`);
+    }
+  });
+
+// ── search ──
+
+program
+  .command("search")
+  .description("Search memory")
+  .argument("<query>", "Search query")
+  .option("--tags <tags>", "Filter by tags (comma-separated)")
+  .option("--max-results <n>", "Maximum results", "10")
+  .action((query: string, opts: Record<string, string>) => {
+    const globals = program.opts();
+    const tree = new ContextTree(globals.root);
+    const search = new SearchEngine(path.join(globals.root, "_search.db"));
+
+    search.buildIndex(tree, globals.bank);
+
+    const tags = opts.tags ? opts.tags.split(",").map((t: string) => t.trim()) : undefined;
+    const hits = search.search(query, globals.bank, {
+      limit: parseInt(opts.maxResults || "10", 10),
+      tags,
+    });
+    search.close();
+
+    if (globals.format === "json") {
+      const hitDicts = hits.map((h) => ({
+        score: Math.round(h.score * 10000) / 10000,
+        text: h.text,
+        domain: h.domain,
+        file: h.file_path,
+        memory_id: h.id,
+      }));
+      console.log(JSON.stringify({ hits: hitDicts }));
+    } else {
+      if (hits.length === 0) {
+        console.log("No results found.");
+      }
+      for (const h of hits) {
+        console.log(`[${h.score.toFixed(2)}] ${h.file_path}`);
+        console.log(`  ${h.text.slice(0, 100)}`);
+        console.log();
+      }
+    }
+  });
+
+// ── browse ──
+
+program
+  .command("browse")
+  .description("Browse the Context Tree")
+  .argument("[path]", "Path to browse", "")
+  .action((browsePath: string) => {
+    const globals = program.opts();
+    const tree = new ContextTree(globals.root);
+
+    if (!browsePath) {
+      const domains = tree.listDomains(globals.bank);
+      const total = tree.count(globals.bank);
+      if (globals.format === "json") {
+        console.log(JSON.stringify({ path: "", domains, total_memories: total }));
+      } else {
+        console.log(`${globals.root}/memory/`);
+        for (const d of domains) {
+          const count = tree.listEntries(globals.bank, d).length;
+          console.log(`  ${d}/     (${count} entries)`);
+        }
+        console.log(`\nTotal: ${total} memories`);
+      }
+    } else {
+      const entries = tree.listEntries(globals.bank, browsePath);
+      if (globals.format === "json") {
+        const entryDicts = entries.map((e) => ({
+          file: e.file_path,
+          title: e.text.slice(0, 80),
+          memory_id: e.id,
+        }));
+        console.log(JSON.stringify({ path: browsePath, entries: entryDicts }));
+      } else {
+        for (const e of entries) {
+          console.log(`  ${e.file_path}  [${e.id}]`);
+          console.log(`    ${e.text.slice(0, 80)}`);
+        }
+      }
+    }
+  });
+
+// ── forget ──
+
+program
+  .command("forget")
+  .description("Remove memories")
+  .argument("[ids...]", "Memory IDs to delete")
+  .option("--all", "Delete all in bank")
+  .action((ids: string[], opts: Record<string, boolean>) => {
+    const globals = program.opts();
+    const tree = new ContextTree(globals.root);
+    const search = new SearchEngine(path.join(globals.root, "_search.db"));
+    let deleted = 0;
+
+    if (opts.all) {
+      const entries = tree.listEntries(globals.bank);
+      for (const e of entries) {
+        if (tree.delete(e.id)) {
+          search.removeDocument(e.id);
+          deleted++;
+        }
+      }
+    } else {
+      for (const mid of ids) {
+        if (tree.delete(mid)) {
+          search.removeDocument(mid);
+          deleted++;
+        }
+      }
+    }
+    search.close();
+
+    if (globals.format === "json") {
+      console.log(JSON.stringify({ deleted_count: deleted }));
+    } else {
+      console.log(`Deleted ${deleted} memories`);
+    }
+  });
+
+// ── export ──
+
+program
+  .command("export")
+  .description("Export to AMA format")
+  .option("-o, --output <file>", "Output file path")
+  .action((opts: Record<string, string>) => {
+    const globals = program.opts();
+    const tree = new ContextTree(globals.root);
+    const entries = tree.scanAll(globals.bank);
+
+    const header = {
+      _ama_version: 1,
+      bank_id: globals.bank,
+      memory_count: entries.length,
+    };
+
+    const lines: string[] = [JSON.stringify(header)];
+    for (const e of entries) {
+      const record: Record<string, unknown> = {
+        id: e.id,
+        text: e.text,
+        fact_type: e.fact_type,
+        tags: e.tags,
+        created_at: e.created_at,
+      };
+      if (e.occurred_at) record.occurred_at = e.occurred_at;
+      if (e.source) record.source = e.source;
+      lines.push(JSON.stringify(record));
+    }
+
+    const output = lines.join("\n") + "\n";
+    if (opts.output) {
+      fs.writeFileSync(opts.output, output, "utf-8");
+      console.log(`Exported ${entries.length} memories to ${opts.output}`);
+    } else {
+      process.stdout.write(output);
+    }
+  });
+
+// ── health ──
+
+program
+  .command("health")
+  .description("System health check")
+  .action(() => {
+    const globals = program.opts();
+    const tree = new ContextTree(globals.root);
+    const total = tree.count();
+    const domains = tree.listDomains();
+
+    if (globals.format === "json") {
+      console.log(
+        JSON.stringify({ healthy: true, total_memories: total, root: globals.root })
+      );
+    } else {
+      console.log("Status: healthy");
+      console.log(`Root: ${globals.root}`);
+      console.log(`Memories: ${total}`);
+      console.log(`Domains: ${domains.length > 0 ? domains.join(", ") : "(none)"}`);
+    }
+  });
+
+// ── rebuild-index ──
+
+program
+  .command("rebuild-index")
+  .description("Rebuild the search index")
+  .action(() => {
+    const globals = program.opts();
+    const tree = new ContextTree(globals.root);
+    const search = new SearchEngine(path.join(globals.root, "_search.db"));
+    const count = search.buildIndex(tree);
+    search.close();
+    console.log(`Rebuilt index: ${count} entries`);
+  });
+
+// ── mcp ──
+
+program
+  .command("mcp")
+  .description("Start MCP server")
+  .option("--transport <type>", "Transport type (stdio|sse)", "stdio")
+  .option("--port <n>", "SSE port", "8090")
+  .action(async (opts: Record<string, string>) => {
+    const globals = program.opts();
+    await startMcpServer({
+      root: globals.root,
+      defaultBank: globals.bank,
+      transport: opts.transport as "stdio" | "sse",
+      port: parseInt(opts.port, 10),
+    });
+  });
+
+program.parse();