@astrocyteai/local 0.1.0

package/src/context-tree.ts

@@ -0,0 +1,243 @@
+/**
+ * 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";
+import type { MemoryEntry } from "./types.js";
+
+export class ContextTree {
+  private memoryDir: string;
+
+  constructor(private root: string) {
+    this.memoryDir = path.join(root, "memory");
+    fs.mkdirSync(this.memoryDir, { recursive: true });
+  }
+
+  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 {
+    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: MemoryEntry = {
+      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: string): MemoryEntry | null {
+    for (const entry of this.scanAll()) {
+      if (entry.id === entryId) return entry;
+    }
+    return null;
+  }
+
+  update(entryId: string, content: string): MemoryEntry | null {
+    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: string): boolean {
+    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: string): void {
+    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?: string): string[] {
+    if (!fs.existsSync(this.memoryDir)) return [];
+    const domains: string[] = [];
+    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: string, domain?: string): MemoryEntry[] {
+    const searchDir = domain ? path.join(this.memoryDir, domain) : this.memoryDir;
+    if (!fs.existsSync(searchDir)) return [];
+    const entries: MemoryEntry[] = [];
+    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?: string): MemoryEntry[] {
+    if (!fs.existsSync(this.memoryDir)) return [];
+    const entries: MemoryEntry[] = [];
+    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?: string): number {
+    return this.scanAll(bankId).length;
+  }
+
+  // ── Internal ──
+
+  private makeFilename(content: string): string {
+    let slug = content.slice(0, 50).toLowerCase().trim();
+    slug = slug.replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+    return slug || "memory";
+  }
+
+  private writeEntry(filePath: string, entry: MemoryEntry): void {
+    const frontmatter: Record<string, unknown> = {
+      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");
+  }
+
+  private readFile(filePath: string): MemoryEntry | null {
+    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;
+    }
+  }
+
+  private *allMdFiles(dir?: string): Generator<string> {
+    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/src/curated-retain.ts

@@ -0,0 +1,160 @@
+/**
+ * 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;
+}
+
+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: {
+  content: string;
+  bankId: string;
+  tree: ContextTree;
+  search: SearchEngine;
+  llmProvider: LLMProvider;
+  contextLimit?: number;
+}): Promise<CurationDecision> {
+  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: string;
+  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: string,
+  originalContent: string
+): CurationDecision {
+  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 as CurationDecision["action"],
+      domain,
+      content: data.content || originalContent,
+      memory_layer: memoryLayer as CurationDecision["memory_layer"],
+      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/src/index.ts

@@ -0,0 +1,21 @@
+/**
+ * @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/src/mcp-server.ts

@@ -0,0 +1,282 @@
+/**
+ * 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 interface McpServerOptions {
+  root: string;
+  defaultBank?: string;
+  transport?: "stdio" | "sse";
+  port?: number;
+}
+
+export function createMcpServer(options: McpServerOptions): McpServer {
+  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" as const,
+            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" as const,
+            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" as const,
+              text: JSON.stringify({
+                path: "",
+                domains,
+                entries: [],
+                total_memories: total,
+              }),
+            },
+          ],
+        };
+      }
+
+      const entries = tree.listEntries(bankId, browsePath);
+      return {
+        content: [
+          {
+            type: "text" as const,
+            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: string[] = [];
+
+      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" as const,
+            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" as const,
+            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" as const,
+            text: JSON.stringify({
+              healthy: true,
+              total_memories: total,
+              index_status: "current",
+              root,
+            }),
+          },
+        ],
+      };
+    }
+  );
+
+  return server;
+}
+
+export async function startMcpServer(options: McpServerOptions): Promise<void> {
+  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);
+}