@astrocyteai/local 0.1.0

package/.pnpm-config.json

@@ -0,0 +1 @@
+{"onlyBuiltDependencies":["better-sqlite3","esbuild"]}

package/dist/cli.d.ts

@@ -0,0 +1,16 @@
+#!/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
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,276 @@
+#!/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, opts) => {
+    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 = [];
+        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.split(",").map((t) => t.trim()) : [];
+    const domain = opts.domain || (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, opts) => {
+    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) => 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) => {
+    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, opts) => {
+    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) => {
+    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 = [JSON.stringify(header)];
+    for (const e of entries) {
+        const record = {
+            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) => {
+    const globals = program.opts();
+    await startMcpServer({
+        root: globals.root,
+        defaultBank: globals.bank,
+        transport: opts.transport,
+        port: parseInt(opts.port, 10),
+    });
+});
+program.parse();

package/dist/context-tree.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Context Tree — hierarchical markdown file storage.
+ *
+ * Stores memories as .md files with YAML frontmatter in a
+ * domain-based directory structure. See docs/context-tree-format.md.
+ */
+import type { MemoryEntry } from "./types.js";
+export declare class ContextTree {
+    private root;
+    private memoryDir;
+    constructor(root: string);
+    store(options: {
+        content: string;
+        bank_id: string;
+        domain?: string;
+        tags?: string[];
+        memory_layer?: "fact" | "observation" | "model";
+        fact_type?: "world" | "experience" | "observation";
+        occurred_at?: string;
+        source?: string;
+        metadata?: Record<string, string | number | boolean | null>;
+    }): MemoryEntry;
+    read(entryId: string): MemoryEntry | null;
+    update(entryId: string, content: string): MemoryEntry | null;
+    delete(entryId: string): boolean;
+    recordRecall(entryId: string): void;
+    listDomains(bankId?: string): string[];
+    listEntries(bankId: string, domain?: string): MemoryEntry[];
+    scanAll(bankId?: string): MemoryEntry[];
+    count(bankId?: string): number;
+    private makeFilename;
+    private writeEntry;
+    private readFile;
+    private allMdFiles;
+}

package/dist/context-tree.js

@@ -0,0 +1,228 @@
+/**
+ * Context Tree — hierarchical markdown file storage.
+ *
+ * Stores memories as .md files with YAML frontmatter in a
+ * domain-based directory structure. See docs/context-tree-format.md.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import YAML from "yaml";
+export class ContextTree {
+    root;
+    memoryDir;
+    constructor(root) {
+        this.root = root;
+        this.memoryDir = path.join(root, "memory");
+        fs.mkdirSync(this.memoryDir, { recursive: true });
+    }
+    store(options) {
+        const id = randomUUID().replace(/-/g, "").slice(0, 12);
+        const now = new Date().toISOString();
+        const domain = options.domain || "general";
+        const domainDir = path.join(this.memoryDir, domain);
+        fs.mkdirSync(domainDir, { recursive: true });
+        const filename = this.makeFilename(options.content);
+        let filePath = path.join(domainDir, `${filename}.md`);
+        let counter = 2;
+        while (fs.existsSync(filePath)) {
+            filePath = path.join(domainDir, `${filename}-${counter}.md`);
+            counter++;
+        }
+        const relPath = path.relative(this.memoryDir, filePath);
+        const entry = {
+            id,
+            bank_id: options.bank_id,
+            text: options.content,
+            domain,
+            file_path: relPath,
+            memory_layer: options.memory_layer || "fact",
+            fact_type: options.fact_type || "world",
+            tags: options.tags || [],
+            created_at: now,
+            updated_at: now,
+            occurred_at: options.occurred_at,
+            recall_count: 0,
+            source: options.source,
+            metadata: options.metadata || {},
+        };
+        this.writeEntry(filePath, entry);
+        return entry;
+    }
+    read(entryId) {
+        for (const entry of this.scanAll()) {
+            if (entry.id === entryId)
+                return entry;
+        }
+        return null;
+    }
+    update(entryId, content) {
+        for (const mdFile of this.allMdFiles()) {
+            const entry = this.readFile(mdFile);
+            if (entry && entry.id === entryId) {
+                entry.text = content;
+                entry.updated_at = new Date().toISOString();
+                this.writeEntry(mdFile, entry);
+                return entry;
+            }
+        }
+        return null;
+    }
+    delete(entryId) {
+        for (const mdFile of this.allMdFiles()) {
+            const entry = this.readFile(mdFile);
+            if (entry && entry.id === entryId) {
+                fs.unlinkSync(mdFile);
+                // Remove empty domain directories
+                const parent = path.dirname(mdFile);
+                if (parent !== this.memoryDir) {
+                    try {
+                        const remaining = fs.readdirSync(parent);
+                        if (remaining.length === 0)
+                            fs.rmdirSync(parent);
+                    }
+                    catch { }
+                }
+                return true;
+            }
+        }
+        return false;
+    }
+    recordRecall(entryId) {
+        for (const mdFile of this.allMdFiles()) {
+            const entry = this.readFile(mdFile);
+            if (entry && entry.id === entryId) {
+                entry.recall_count++;
+                entry.last_recalled_at = new Date().toISOString();
+                this.writeEntry(mdFile, entry);
+                return;
+            }
+        }
+    }
+    listDomains(bankId) {
+        if (!fs.existsSync(this.memoryDir))
+            return [];
+        const domains = [];
+        for (const d of fs.readdirSync(this.memoryDir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+            if (!d.isDirectory() || d.name.startsWith("_"))
+                continue;
+            if (!bankId) {
+                domains.push(d.name);
+            }
+            else {
+                const domainPath = path.join(this.memoryDir, d.name);
+                const files = fs.readdirSync(domainPath).filter((f) => f.endsWith(".md"));
+                for (const f of files) {
+                    const entry = this.readFile(path.join(domainPath, f));
+                    if (entry && entry.bank_id === bankId) {
+                        domains.push(d.name);
+                        break;
+                    }
+                }
+            }
+        }
+        return domains;
+    }
+    listEntries(bankId, domain) {
+        const searchDir = domain ? path.join(this.memoryDir, domain) : this.memoryDir;
+        if (!fs.existsSync(searchDir))
+            return [];
+        const entries = [];
+        for (const mdFile of this.allMdFiles(searchDir)) {
+            const entry = this.readFile(mdFile);
+            if (entry && entry.bank_id === bankId)
+                entries.push(entry);
+        }
+        return entries;
+    }
+    scanAll(bankId) {
+        if (!fs.existsSync(this.memoryDir))
+            return [];
+        const entries = [];
+        for (const mdFile of this.allMdFiles()) {
+            const entry = this.readFile(mdFile);
+            if (entry && (!bankId || entry.bank_id === bankId))
+                entries.push(entry);
+        }
+        return entries;
+    }
+    count(bankId) {
+        return this.scanAll(bankId).length;
+    }
+    // ── Internal ──
+    makeFilename(content) {
+        let slug = content.slice(0, 50).toLowerCase().trim();
+        slug = slug.replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+        return slug || "memory";
+    }
+    writeEntry(filePath, entry) {
+        const frontmatter = {
+            id: entry.id,
+            bank_id: entry.bank_id,
+            memory_layer: entry.memory_layer,
+            fact_type: entry.fact_type,
+            tags: entry.tags,
+            created_at: entry.created_at,
+            updated_at: entry.updated_at,
+            recall_count: entry.recall_count,
+        };
+        if (entry.occurred_at)
+            frontmatter.occurred_at = entry.occurred_at;
+        if (entry.last_recalled_at)
+            frontmatter.last_recalled_at = entry.last_recalled_at;
+        if (entry.source)
+            frontmatter.source = entry.source;
+        if (Object.keys(entry.metadata).length > 0)
+            frontmatter.metadata = entry.metadata;
+        const fmStr = YAML.stringify(frontmatter);
+        fs.writeFileSync(filePath, `---\n${fmStr}---\n\n${entry.text}\n`, "utf-8");
+    }
+    readFile(filePath) {
+        try {
+            const content = fs.readFileSync(filePath, "utf-8");
+            if (!content.startsWith("---"))
+                return null;
+            const parts = content.split("---");
+            if (parts.length < 3)
+                return null;
+            const fm = YAML.parse(parts[1]) || {};
+            const text = parts.slice(2).join("---").trim();
+            const relPath = path.relative(this.memoryDir, filePath);
+            const domain = path.dirname(filePath) === this.memoryDir ? "general" : path.basename(path.dirname(filePath));
+            return {
+                id: fm.id || "",
+                bank_id: fm.bank_id || "",
+                text,
+                domain,
+                file_path: relPath,
+                memory_layer: fm.memory_layer || "fact",
+                fact_type: fm.fact_type || "world",
+                tags: fm.tags || [],
+                created_at: fm.created_at || "",
+                updated_at: fm.updated_at || "",
+                occurred_at: fm.occurred_at,
+                recall_count: fm.recall_count || 0,
+                last_recalled_at: fm.last_recalled_at,
+                source: fm.source,
+                metadata: fm.metadata || {},
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    *allMdFiles(dir) {
+        const searchDir = dir || this.memoryDir;
+        if (!fs.existsSync(searchDir))
+            return;
+        for (const entry of fs.readdirSync(searchDir, { withFileTypes: true })) {
+            const fullPath = path.join(searchDir, entry.name);
+            if (entry.isDirectory() && !entry.name.startsWith("_")) {
+                yield* this.allMdFiles(fullPath);
+            }
+            else if (entry.isFile() && entry.name.endsWith(".md")) {
+                yield fullPath;
+            }
+        }
+    }
+}

package/dist/curated-retain.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 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.
+ */
+import type { ContextTree } from "./context-tree.js";
+import type { SearchEngine } from "./search.js";
+export interface LLMProvider {
+    complete(options: {
+        messages: Array<{
+            role: string;
+            content: string;
+        }>;
+        maxTokens?: number;
+        temperature?: number;
+    }): Promise<{
+        text: string;
+    }>;
+}
+export interface CurationDecision {
+    action: "add" | "update" | "merge" | "skip" | "delete";
+    domain: string;
+    content: string;
+    memory_layer: "fact" | "observation" | "model";
+    reasoning: string;
+    target_id?: string;
+}
+export declare function curateLocalRetain(options: {
+    content: string;
+    bankId: string;
+    tree: ContextTree;
+    search: SearchEngine;
+    llmProvider: LLMProvider;
+    contextLimit?: number;
+}): Promise<CurationDecision>;
+export declare function parseResponse(response: string, originalContent: string): CurationDecision;