@engram-cli/engram 0.1.0 → 0.1.1

package/bundled-backend/project-index.js

@@ -0,0 +1,74 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { config } from "./config.js";
+const PROJECTS_FILE = path.join(config.dataDir, "projects.json");
+async function ensureDataDir() {
+    await fs.mkdir(config.dataDir, { recursive: true });
+}
+export async function readProjects() {
+    try {
+        const raw = await fs.readFile(PROJECTS_FILE, "utf8");
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed.projects) ? parsed.projects : [];
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        throw err;
+    }
+}
+async function writeProjects(projects) {
+    await ensureDataDir();
+    await fs.writeFile(PROJECTS_FILE, JSON.stringify({ projects }, null, 2), "utf8");
+}
+export async function upsertProject(slug, opts = {}) {
+    const projects = await readProjects();
+    const seen = opts.seen ?? new Date().toISOString();
+    const existing = projects.find((p) => p.slug === slug);
+    if (existing) {
+        existing.last_seen = seen;
+        if (opts.ide && !existing.ides.includes(opts.ide)) {
+            existing.ides.push(opts.ide);
+        }
+    }
+    else {
+        projects.push({
+            slug,
+            last_seen: seen,
+            ides: opts.ide ? [opts.ide] : ["unknown"],
+        });
+    }
+    await writeProjects(projects);
+}
+export async function seedProjectsFromCapsules() {
+    const projects = await readProjects();
+    if (projects.length)
+        return;
+    const capsulesDir = path.join(config.dataDir, "capsules");
+    try {
+        const entries = await fs.readdir(capsulesDir, { withFileTypes: true });
+        const newProjects = [];
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            const current = path.join(capsulesDir, entry.name, "current.json");
+            try {
+                const raw = await fs.readFile(current, "utf8");
+                const capsule = JSON.parse(raw);
+                newProjects.push({
+                    slug: entry.name,
+                    last_seen: capsule.created_at ?? new Date().toISOString(),
+                    ides: capsule.source_ide ? [capsule.source_ide] : ["unknown"],
+                });
+            }
+            catch {
+                // skip projects without a current capsule
+            }
+        }
+        if (newProjects.length)
+            await writeProjects(newProjects);
+    }
+    catch {
+        // directory doesn't exist yet; ignore
+    }
+}

package/bundled-backend/project-slug.js

@@ -0,0 +1,18 @@
+import path from "node:path";
+const UNSAFE = /(?:\.\.|\/|\\|[\0])/;
+const MAX_SLUG_LEN = 80;
+/** Reject path traversal and unsafe project slugs before filesystem use. */
+export function assertSafeProjectSlug(raw) {
+    const slug = raw.trim().toLowerCase();
+    if (!slug || slug.length > MAX_SLUG_LEN) {
+        throw new Error("invalid_project_slug");
+    }
+    if (UNSAFE.test(slug) || slug === "." || slug === "..") {
+        throw new Error("invalid_project_slug");
+    }
+    const resolved = path.basename(slug);
+    if (resolved !== slug) {
+        throw new Error("invalid_project_slug");
+    }
+    return slug;
+}

package/bundled-backend/routes/capsule.js

@@ -0,0 +1,77 @@
+import { Hono } from "hono";
+import { z } from "zod";
+import { assembleCapsule } from "../capsule-assembler.js";
+import { ensureCurrentCapsule, listCapsules, loadCapsule, saveCapsule, } from "../capsule-store.js";
+export const capsuleRoutes = new Hono();
+const SaveBody = z.object({
+    project: z.string().min(1),
+    ide: z.string().optional(),
+    project_root: z.string().optional(),
+    /** Ignored — one capsule per project; existing id is reused. */
+    capsule_id: z.string().optional(),
+});
+const LoadBody = z.object({
+    project: z.string().min(1),
+    /** Optional for back-compat; ignored — load always uses current.json. */
+    capsule_id: z.string().optional(),
+});
+capsuleRoutes.post("/capsule/save", async (c) => {
+    let body;
+    try {
+        body = await c.req.json();
+    }
+    catch {
+        return c.json({ error: "invalid_json" }, 400);
+    }
+    const parsed = SaveBody.safeParse(body);
+    if (!parsed.success) {
+        return c.json({ error: "invalid_body", details: parsed.error.flatten() }, 400);
+    }
+    try {
+        const existing = await ensureCurrentCapsule(parsed.data.project);
+        const assembled = await assembleCapsule({
+            project: parsed.data.project,
+            capsuleId: existing?.capsule_id,
+            sourceIde: parsed.data.ide,
+            // Preserve original created_at on upsert; content is refreshed
+            createdAt: existing?.created_at,
+        });
+        const saved = await saveCapsule(assembled, {
+            projectRoot: parsed.data.project_root,
+        });
+        return c.json(saved, existing ? 200 : 201);
+    }
+    catch (err) {
+        console.error("[engram] capsule save failed:", err);
+        return c.json({
+            error: "capsule_save_failed",
+            message: err instanceof Error ? err.message : String(err),
+        }, 502);
+    }
+});
+capsuleRoutes.post("/capsule/load", async (c) => {
+    let body;
+    try {
+        body = await c.req.json();
+    }
+    catch {
+        return c.json({ error: "invalid_json" }, 400);
+    }
+    const parsed = LoadBody.safeParse(body);
+    if (!parsed.success) {
+        return c.json({ error: "invalid_body", details: parsed.error.flatten() }, 400);
+    }
+    const capsule = await loadCapsule(parsed.data.project);
+    if (!capsule) {
+        return c.json({ error: "not_found" }, 404);
+    }
+    return c.json(capsule);
+});
+capsuleRoutes.get("/capsule/list", async (c) => {
+    const project = c.req.query("project")?.trim();
+    if (!project) {
+        return c.json({ error: "project_required" }, 400);
+    }
+    const items = await listCapsules(project);
+    return c.json({ project, capsules: items });
+});

package/bundled-backend/routes/context.js

@@ -0,0 +1,23 @@
+import { Hono } from "hono";
+import { assembleCapsule } from "../capsule-assembler.js";
+export const contextRoutes = new Hono();
+contextRoutes.get("/context", async (c) => {
+    const project = c.req.query("project")?.trim();
+    if (!project) {
+        return c.json({ error: "project_required" }, 400);
+    }
+    try {
+        const capsule = await assembleCapsule({
+            project,
+            sourceIde: c.req.query("ide") ?? undefined,
+        });
+        return c.json(capsule);
+    }
+    catch (err) {
+        console.error("[engram] context failed:", err);
+        return c.json({
+            error: "context_failed",
+            message: err instanceof Error ? err.message : String(err),
+        }, 502);
+    }
+});

package/bundled-backend/routes/event.js

@@ -0,0 +1,70 @@
+import { Hono } from "hono";
+import { MemoryEventSchema, deterministicFactString, projectContainerTag, } from "@engram-cli/contracts";
+import { intentFilter } from "../intent-filter.js";
+import { getSupermemory } from "../supermemory.js";
+import { upsertProject } from "../project-index.js";
+export const eventRoutes = new Hono();
+eventRoutes.post("/event", async (c) => {
+    let body;
+    try {
+        body = await c.req.json();
+    }
+    catch {
+        return c.json({ error: "invalid_json" }, 400);
+    }
+    const parsed = MemoryEventSchema.safeParse(body);
+    if (!parsed.success) {
+        return c.json({ error: "invalid_event", details: parsed.error.flatten() }, 400);
+    }
+    const filtered = intentFilter(parsed.data);
+    if (!filtered.keep) {
+        return c.json({ accepted: false, dropped: true, reason: filtered.reason }, 202);
+    }
+    const event = filtered.event;
+    const containerTag = projectContainerTag(event.project);
+    const content = deterministicFactString(event);
+    const metadata = {
+        ide: event.ide ?? "unknown",
+        source: event.source,
+        event_type: event.event_type,
+        session_id: event.session_id,
+        timestamp: event.timestamp,
+    };
+    if (event.file_path)
+        metadata.file_path = event.file_path;
+    if (event.line != null)
+        metadata.line = event.line;
+    if (event.exit_code != null)
+        metadata.exit_code = event.exit_code;
+    if (event.cwd)
+        metadata.cwd = event.cwd;
+    if (event.chat_label)
+        metadata.chat_label = event.chat_label;
+    try {
+        const sm = getSupermemory();
+        const [result] = await Promise.all([
+            sm.add({
+                content,
+                containerTag,
+                metadata,
+            }),
+            upsertProject(event.project, {
+                seen: event.timestamp,
+                ide: event.ide ?? (event.source === "terminal" ? "terminal" : event.source === "git" ? "git" : "unknown"),
+            }),
+        ]);
+        return c.json({
+            accepted: true,
+            dropped: false,
+            containerTag,
+            id: result.id,
+        }, 202);
+    }
+    catch (err) {
+        console.error("[engram] add failed:", err);
+        return c.json({
+            error: "supermemory_add_failed",
+            message: err instanceof Error ? err.message : String(err),
+        }, 502);
+    }
+});

package/bundled-backend/routes/global-settings.js

@@ -0,0 +1,125 @@
+import { Hono } from "hono";
+import { z } from "zod";
+import { config, reloadSupermemoryKey } from "../config.js";
+import { detectLlmProvider, envFilePath, LLM_ENV_KEYS, maskKey, readEnvValue, supermemoryApiKeyPath, supermemoryEnvPath, upsertEnvValue, } from "../env-files.js";
+import fs from "node:fs";
+import path from "node:path";
+export const globalSettingsRoutes = new Hono();
+const PutBody = z.object({
+    supermemory_api_key: z.string().min(1).optional(),
+    supermemory_base_url: z.string().url().optional(),
+    llm_provider: z.enum(["groq", "openai", "anthropic"]).optional(),
+    llm_api_key: z.string().min(1).optional(),
+    clear_llm: z.boolean().optional(),
+});
+function buildResponse(restart = false) {
+    const envPath = envFilePath();
+    const key = readEnvValue(envPath, "SUPERMEMORY_API_KEY") ||
+        config.supermemoryApiKey ||
+        undefined;
+    const llm = detectLlmProvider();
+    return {
+        supermemory: maskKey(key),
+        llm: { provider: llm.provider, configured: llm.configured },
+        supermemory_url: readEnvValue(envPath, "SUPERMEMORY_BASE_URL") ||
+            config.supermemoryBaseUrl,
+        backend_url: `http://localhost:${config.port}`,
+        env_path: envPath,
+        restart_recommended: restart,
+    };
+}
+globalSettingsRoutes.get("/settings/global", (c) => {
+    return c.json(buildResponse(false));
+});
+globalSettingsRoutes.put("/settings/global", async (c) => {
+    let body;
+    try {
+        body = await c.req.json();
+    }
+    catch {
+        return c.json({ error: "invalid_json" }, 400);
+    }
+    const parsed = PutBody.safeParse(body);
+    if (!parsed.success) {
+        return c.json({ error: "invalid_body", details: parsed.error.flatten() }, 400);
+    }
+    const data = parsed.data;
+    if (!data.supermemory_api_key &&
+        !data.llm_api_key &&
+        !data.clear_llm &&
+        !data.supermemory_base_url) {
+        return c.json({ error: "nothing_to_update" }, 400);
+    }
+    if (data.llm_api_key && !data.llm_provider) {
+        return c.json({ error: "llm_provider_required", message: "llm_provider is required when setting llm_api_key" }, 400);
+    }
+    const envPath = envFilePath();
+    let restart = false;
+    try {
+        if (data.supermemory_api_key) {
+            upsertEnvValue(envPath, "SUPERMEMORY_API_KEY", data.supermemory_api_key);
+            const base = data.supermemory_base_url ||
+                readEnvValue(envPath, "SUPERMEMORY_BASE_URL") ||
+                "http://localhost:6767";
+            upsertEnvValue(envPath, "SUPERMEMORY_BASE_URL", base);
+            // Keep ~/.supermemory/api-key in sync for Local
+            const smDir = path.dirname(supermemoryApiKeyPath());
+            fs.mkdirSync(smDir, { recursive: true });
+            fs.writeFileSync(supermemoryApiKeyPath(), data.supermemory_api_key, "utf8");
+            reloadSupermemoryKey(data.supermemory_api_key, base);
+            restart = true;
+        }
+        else if (data.supermemory_base_url) {
+            upsertEnvValue(envPath, "SUPERMEMORY_BASE_URL", data.supermemory_base_url);
+            reloadSupermemoryKey(config.supermemoryApiKey, data.supermemory_base_url);
+            restart = true;
+        }
+        if (data.clear_llm) {
+            const smEnv = supermemoryEnvPath();
+            for (const envKey of Object.values(LLM_ENV_KEYS)) {
+                // Clear by writing empty? Better: remove lines. upsert empty is fine for "not configured"
+                try {
+                    const text = fs.readFileSync(smEnv, "utf8");
+                    const next = text
+                        .split("\n")
+                        .filter((line) => !Object.values(LLM_ENV_KEYS).some((k) => line.startsWith(`${k}=`)))
+                        .join("\n");
+                    fs.writeFileSync(smEnv, next.endsWith("\n") || !next ? next : `${next}\n`, "utf8");
+                }
+                catch {
+                    // no file yet
+                }
+            }
+        }
+        else if (data.llm_api_key && data.llm_provider) {
+            const smEnv = supermemoryEnvPath();
+            // Clear other provider keys so detectLlmProvider is unambiguous
+            for (const [provider, envKey] of Object.entries(LLM_ENV_KEYS)) {
+                if (provider === data.llm_provider) {
+                    upsertEnvValue(smEnv, envKey, data.llm_api_key);
+                }
+                else {
+                    try {
+                        const text = fs.readFileSync(smEnv, "utf8");
+                        const next = text
+                            .split("\n")
+                            .filter((line) => !line.startsWith(`${envKey}=`))
+                            .join("\n");
+                        fs.writeFileSync(smEnv, next.endsWith("\n") || !next ? next : `${next}\n`, "utf8");
+                    }
+                    catch {
+                        // ignore
+                    }
+                }
+            }
+        }
+    }
+    catch (err) {
+        console.error("[engram] global settings write failed:", err);
+        return c.json({
+            error: "write_failed",
+            message: err instanceof Error ? err.message : String(err),
+        }, 500);
+    }
+    return c.json(buildResponse(restart));
+});

package/bundled-backend/routes/health.js

@@ -0,0 +1,24 @@
+import { Hono } from "hono";
+import { config } from "../config.js";
+import { detectLlmProvider, envFilePath, maskKey, readEnvValue, } from "../env-files.js";
+import { probeSupermemory } from "../supermemory.js";
+import { isSupabaseConfigured, probeSupabase } from "../supabase.js";
+export const healthRoutes = new Hono();
+healthRoutes.get("/health", async (c) => {
+    const supermemory = await probeSupermemory();
+    const supabase = isSupabaseConfigured() ? await probeSupabase() : null;
+    const envPath = envFilePath();
+    const key = readEnvValue(envPath, "SUPERMEMORY_API_KEY") ||
+        config.supermemoryApiKey ||
+        undefined;
+    const llm = detectLlmProvider();
+    return c.json({
+        ok: true,
+        supermemory,
+        supabase,
+        keys: {
+            supermemory: maskKey(key),
+            llm: { provider: llm.provider, configured: llm.configured },
+        },
+    });
+});

package/bundled-backend/routes/projects.js

@@ -0,0 +1,100 @@
+import { Hono } from "hono";
+import { getSupermemory } from "../supermemory.js";
+import { projectContainerTag, } from "@engram-cli/contracts";
+import { readProjects, seedProjectsFromCapsules, } from "../project-index.js";
+function metaString(meta, key) {
+    const v = meta?.[key];
+    if (typeof v === "string" && v !== "")
+        return v;
+    return undefined;
+}
+function asMeta(meta) {
+    return meta ?? undefined;
+}
+async function listDocs(containerTag, limit) {
+    const sm = getSupermemory();
+    const res = await sm.documents.list({
+        containerTags: [containerTag],
+        includeContent: true,
+        limit,
+        sort: "createdAt",
+        order: "desc",
+    });
+    return (res.memories ?? []).map((m) => ({
+        id: m.id,
+        content: m.content,
+        summary: m.summary,
+        title: m.title,
+        createdAt: m.createdAt,
+        metadata: asMeta(m.metadata),
+    }));
+}
+function previewOf(doc) {
+    return (doc.content || doc.summary || doc.title || "").trim().slice(0, 200);
+}
+function ideOf(doc) {
+    const source = metaString(doc.metadata, "source");
+    return metaString(doc.metadata, "ide") ?? (source === "terminal" ? "terminal" : source === "git" ? "git" : "unknown");
+}
+export const projectRoutes = new Hono();
+projectRoutes.get("/projects", async (c) => {
+    await seedProjectsFromCapsules();
+    const projects = await readProjects();
+    projects.sort((a, b) => b.last_seen.localeCompare(a.last_seen));
+    return c.json({ projects });
+});
+projectRoutes.get("/projects/:slug", async (c) => {
+    await seedProjectsFromCapsules();
+    const slug = c.req.param("slug");
+    const projects = await readProjects();
+    const project = projects.find((p) => p.slug === slug);
+    if (!project)
+        return c.json({ error: "project_not_found" }, 404);
+    return c.json({ project });
+});
+projectRoutes.get("/projects/:slug/feed", async (c) => {
+    const slug = c.req.param("slug");
+    const limit = Math.min(Number(c.req.query("limit") ?? 50), 200);
+    const containerTag = projectContainerTag(slug);
+    const docs = await listDocs(containerTag, limit);
+    const items = docs.map((doc) => ({
+        id: doc.id,
+        event_type: metaString(doc.metadata, "event_type"),
+        source: metaString(doc.metadata, "source"),
+        ide: ideOf(doc),
+        preview: previewOf(doc),
+        file_path: metaString(doc.metadata, "file_path"),
+        timestamp: metaString(doc.metadata, "timestamp") ?? doc.createdAt,
+    }));
+    return c.json({ project: slug, total: items.length, items });
+});
+projectRoutes.get("/projects/:slug/clusters", async (c) => {
+    const slug = c.req.param("slug");
+    const limit = Math.min(Number(c.req.query("limit") ?? 100), 200);
+    const containerTag = projectContainerTag(slug);
+    const docs = await listDocs(containerTag, limit);
+    const byIde = {};
+    for (const doc of docs) {
+        const ide = ideOf(doc);
+        const bucket = byIde[ide] ?? { count: 0, recent: [] };
+        bucket.count++;
+        if (bucket.recent.length < 5) {
+            bucket.recent.push({
+                preview: previewOf(doc),
+                event_type: metaString(doc.metadata, "event_type"),
+                timestamp: metaString(doc.metadata, "timestamp") ?? doc.createdAt ?? undefined,
+            });
+        }
+        byIde[ide] = bucket;
+    }
+    return c.json({ project: slug, by_ide: byIde });
+});
+projectRoutes.get("/projects/:slug/ides", async (c) => {
+    const slug = c.req.param("slug");
+    const containerTag = projectContainerTag(slug);
+    const docs = await listDocs(containerTag, 1000);
+    const ides = new Set();
+    for (const doc of docs)
+        ides.add(ideOf(doc));
+    return c.json({ project: slug, ides: Array.from(ides) });
+});

package/bundled-backend/routes/search.js

@@ -0,0 +1,69 @@
+import { Hono } from "hono";
+import { z } from "zod";
+import { projectContainerTag } from "@engram-cli/contracts";
+import { config } from "../config.js";
+import { getSupermemory } from "../supermemory.js";
+export const searchRoutes = new Hono();
+const SearchBody = z.object({
+    q: z.string().min(1),
+    project: z.string().min(1),
+    limit: z.number().int().positive().max(20).optional(),
+});
+/** Self-hosted Local often lacks Workers AI rerank (`x.AI.run`); hybrid chunks still work. */
+function preferRerank() {
+    if (process.env.ENGRAM_SEARCH_RERANK === "true")
+        return true;
+    if (process.env.ENGRAM_SEARCH_RERANK === "false")
+        return false;
+    return !/localhost|127\.0\.0\.1/.test(config.supermemoryBaseUrl);
+}
+searchRoutes.post("/search", async (c) => {
+    let body;
+    try {
+        body = await c.req.json();
+    }
+    catch {
+        return c.json({ error: "invalid_json" }, 400);
+    }
+    const parsed = SearchBody.safeParse(body);
+    if (!parsed.success) {
+        return c.json({ error: "invalid_body", details: parsed.error.flatten() }, 400);
+    }
+    const containerTag = projectContainerTag(parsed.data.project);
+    const sm = getSupermemory();
+    const base = {
+        q: parsed.data.q,
+        containerTag,
+        searchMode: "hybrid",
+        threshold: 0.55,
+        limit: parsed.data.limit ?? 8,
+    };
+    try {
+        let rerank = preferRerank();
+        let results;
+        try {
+            results = await sm.search.memories({ ...base, rerank });
+        }
+        catch (err) {
+            if (!rerank)
+                throw err;
+            console.warn("[engram] search with rerank failed; retrying without:", err instanceof Error ? err.message : err);
+            rerank = false;
+            results = await sm.search.memories({ ...base, rerank: false });
+        }
+        return c.json({
+            project: parsed.data.project,
+            containerTag,
+            rerank,
+            total: results.total ?? results.results?.length ?? 0,
+            results: results.results ?? [],
+        });
+    }
+    catch (err) {
+        console.error("[engram] search failed:", err);
+        return c.json({
+            error: "search_failed",
+            message: err instanceof Error ? err.message : String(err),
+        }, 502);
+    }
+});

package/bundled-backend/routes/settings.js

@@ -0,0 +1,82 @@
+import { Hono } from "hono";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { config } from "../config.js";
+const DEFAULT_SETTINGS = {
+    retention_days: 14,
+    max_mb: 50,
+    capture_toggles: {
+        file_open: true,
+        file_save: true,
+        error: true,
+        command: true,
+        branch_switch: true,
+        commit: true,
+        code_selection: true,
+        clipboard: true,
+        chat_summary: true,
+    },
+};
+const SettingsUpdateSchema = z.object({
+    retention_days: z.number().int().min(1).max(365).optional(),
+    max_mb: z.number().int().min(1).max(1000).optional(),
+    capture_toggles: z.record(z.boolean()).optional(),
+});
+function settingsPath(slug) {
+    return path.join(config.dataDir, "settings", `${slug}.json`);
+}
+export async function loadSettings(slug) {
+    try {
+        const raw = await fs.readFile(settingsPath(slug), "utf8");
+        const parsed = JSON.parse(raw);
+        return {
+            ...DEFAULT_SETTINGS,
+            ...parsed,
+            capture_toggles: {
+                ...DEFAULT_SETTINGS.capture_toggles,
+                ...(parsed.capture_toggles ?? {}),
+            },
+        };
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return { ...DEFAULT_SETTINGS };
+        throw err;
+    }
+}
+export async function saveSettings(slug, settings) {
+    await fs.mkdir(path.join(config.dataDir, "settings"), { recursive: true });
+    await fs.writeFile(settingsPath(slug), JSON.stringify(settings, null, 2), "utf8");
+}
+export const settingsRoutes = new Hono();
+settingsRoutes.get("/projects/:slug/settings", async (c) => {
+    const slug = c.req.param("slug");
+    const settings = await loadSettings(slug);
+    return c.json({ project: slug, settings });
+});
+settingsRoutes.put("/projects/:slug/settings", async (c) => {
+    const slug = c.req.param("slug");
+    let body;
+    try {
+        body = await c.req.json();
+    }
+    catch {
+        return c.json({ error: "invalid_json" }, 400);
+    }
+    const parsed = SettingsUpdateSchema.safeParse(body);
+    if (!parsed.success) {
+        return c.json({ error: "invalid_settings", details: parsed.error.flatten() }, 400);
+    }
+    const current = await loadSettings(slug);
+    const next = {
+        retention_days: parsed.data.retention_days ?? current.retention_days,
+        max_mb: parsed.data.max_mb ?? current.max_mb,
+        capture_toggles: {
+            ...current.capture_toggles,
+            ...(parsed.data.capture_toggles ?? {}),
+        },
+    };
+    await saveSettings(slug, next);
+    return c.json({ project: slug, settings: next });
+});