@iamem/amem 0.1.0

package/dist/mcp.js

@@ -0,0 +1,435 @@
+import { existsSync } from "node:fs";
+import { handleApi } from "./api/routes.js";
+import { getRepoByName } from "./db.js";
+const PROTOCOL_VERSIONS = new Set(["2024-11-05", "2025-03-26", "2025-06-18"]);
+const TOOLS = [
+    {
+        name: "amem_context",
+        description: "Retrieve compact local amem memory for a query. Use before exploring files or calling a remote LLM with a large prompt. Pass workspace for named app memory, not only git repos.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: { type: "string" },
+                workspace: { type: "string", description: "Named workspace (not a git repo)" },
+                platform: { type: "string" },
+                sessionId: { type: "string" },
+            },
+            required: ["query"],
+        },
+    },
+    {
+        name: "amem_recipe",
+        description: "Return the generic amem remember contract: when to call amem_context vs amem_remember. Use if you are unsure whether to read or write memory. Same recipe for every MCP host.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "amem_remember",
+        description: "Store a durable local fact in amem (stays on this machine).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                text: { type: "string" },
+                workspace: { type: "string" },
+                kind: { type: "string" },
+                anchors: { type: "array", items: { type: "string" } },
+            },
+            required: ["text"],
+        },
+    },
+    {
+        name: "amem_repos",
+        description: "List what amem is monitoring. Each item has kind git or workspace. Workspaces also have a stable slug (MCP id); the display name can differ. Use when asked which projects, workspaces, or repos amem knows about.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                kind: {
+                    type: "string",
+                    description: "all (default), git, or workspace",
+                },
+            },
+        },
+    },
+    {
+        name: "amem_stats",
+        description: "Usage and savings stats (local lookup time, estimated tokens/ms saved, hit rate) for one workspace/repo or everything. Use when asked how much amem helped, how often it hit, or usage over time.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                workspace: { type: "string" },
+                days: { type: "number", description: "Lookback window (default 30)" },
+                scope: {
+                    type: "string",
+                    description: "all (every tracked repo/workspace) or current (the given workspace / cwd)",
+                },
+            },
+        },
+    },
+    {
+        name: "amem_graph",
+        description: "Dump stored facts for a workspace or git repo: claims, components, flows, and recent activity. Use when asked what amem remembers about a project. Prefer amem_context for a ranked packet for the current question.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                workspace: { type: "string" },
+                days: { type: "number", description: "Activity lookback (default 30)" },
+            },
+        },
+    },
+    {
+        name: "amem_status",
+        description: "Binding, policy, and counts for one workspace/repo, plus the full monitored inventory. Omit workspace for a machine-wide overview.",
+        inputSchema: {
+            type: "object",
+            properties: { workspace: { type: "string" } },
+        },
+    },
+];
+function textResult(text, isError = false) {
+    return {
+        content: [{ type: "text", text }],
+        isError,
+    };
+}
+function defaultWorkspace(explicit, fallback) {
+    if (typeof explicit === "string" && explicit.trim())
+        return explicit.trim();
+    if (fallback?.trim())
+        return fallback.trim();
+    return process.env.AMEM_WORKSPACE || undefined;
+}
+function api(method, pathname, body, opts) {
+    const searchParams = new URLSearchParams();
+    if (opts?.workspace)
+        searchParams.set("workspace", opts.workspace);
+    for (const [key, value] of Object.entries(opts?.query ?? {})) {
+        if (value)
+            searchParams.set(key, value);
+    }
+    return handleApi({
+        method,
+        pathname,
+        searchParams,
+        body,
+        cwd: process.cwd(),
+    });
+}
+function jsonResult(value, isError = false) {
+    return textResult(JSON.stringify(value, null, 2), isError);
+}
+function apiResult(result) {
+    if (result.status >= 400)
+        return jsonResult(result.body, true);
+    return jsonResult(result.body);
+}
+function parseDays(value, fallback = 30) {
+    const n = typeof value === "number" ? value : typeof value === "string" ? Number(value) : fallback;
+    if (!Number.isFinite(n) || n <= 0)
+        return String(fallback);
+    return String(Math.min(365, Math.floor(n)));
+}
+function compactGraph(body) {
+    if (!body || typeof body !== "object")
+        return body;
+    const g = body;
+    const claims = (g.claims ?? []).slice(0, 80).map((c) => ({
+        id: c.id,
+        kind: c.kind,
+        text: c.text,
+        anchors: (() => {
+            try {
+                return JSON.parse(c.code_anchors);
+            }
+            catch {
+                return c.code_anchors;
+            }
+        })(),
+    }));
+    return {
+        claims,
+        claimCount: (g.claims ?? []).length,
+        truncated: (g.claims ?? []).length > claims.length,
+        components: (g.components ?? []).map((c) => ({
+            id: c.id,
+            name: c.name,
+            anchor: c.code_anchor,
+        })),
+        flows: g.flows ?? [],
+        recentClaimIds: g.recentClaimIds ?? [],
+        activity: g.activity,
+    };
+}
+function compactStats(body) {
+    if (!body || typeof body !== "object")
+        return body;
+    const s = body;
+    return {
+        scope: s.scope,
+        days: s.days,
+        aggregate: s.aggregate,
+        repos: s.repos,
+    };
+}
+function callTool(name, args, fallbackWorkspace) {
+    const workspace = defaultWorkspace(args.workspace, fallbackWorkspace);
+    if (name === "amem_context") {
+        const query = typeof args.query === "string" ? args.query : "";
+        if (!query.trim())
+            return textResult("query is required", true);
+        const result = api("POST", "/api/context", {
+            query,
+            workspace,
+            platform: typeof args.platform === "string" ? args.platform : "mcp",
+            sessionId: typeof args.sessionId === "string" ? args.sessionId : undefined,
+        }, { workspace });
+        if (result.status >= 400) {
+            return textResult(JSON.stringify(result.body), true);
+        }
+        const body = result.body;
+        return textResult(body.markdown || JSON.stringify(result.body));
+    }
+    if (name === "amem_recipe") {
+        const result = api("GET", "/api/recipe", null);
+        if (result.status >= 400)
+            return apiResult(result);
+        const contract = result.body;
+        return textResult(contract.paste || contract.markdown || JSON.stringify(result.body));
+    }
+    if (name === "amem_remember") {
+        const text = typeof args.text === "string" ? args.text : "";
+        if (!text.trim())
+            return textResult("text is required", true);
+        const result = api("POST", "/api/remember", {
+            text,
+            workspace,
+            kind: typeof args.kind === "string" ? args.kind : "session",
+            anchors: args.anchors,
+            source: "mcp",
+        }, { workspace });
+        if (result.status >= 400)
+            return textResult(JSON.stringify(result.body), true);
+        return textResult(JSON.stringify(result.body));
+    }
+    if (name === "amem_repos") {
+        const result = api("GET", "/api/repos", null);
+        if (result.status >= 400)
+            return apiResult(result);
+        const kind = typeof args.kind === "string" ? args.kind.trim().toLowerCase() : "all";
+        const repos = (result.body.repos ?? []).filter((r) => {
+            if (kind === "git" || kind === "workspace")
+                return r.kind === kind;
+            return true;
+        });
+        return jsonResult({
+            count: repos.length,
+            kind: kind === "git" || kind === "workspace" ? kind : "all",
+            repos,
+        });
+    }
+    if (name === "amem_stats") {
+        const scope = typeof args.scope === "string" && args.scope.trim()
+            ? args.scope.trim()
+            : workspace
+                ? "current"
+                : "all";
+        const result = api("GET", "/api/usage", null, {
+            workspace,
+            query: { scope, days: parseDays(args.days) },
+        });
+        if (result.status >= 400)
+            return apiResult(result);
+        return jsonResult(compactStats(result.body));
+    }
+    if (name === "amem_graph") {
+        const result = api("GET", "/api/graph", null, {
+            workspace,
+            query: { days: parseDays(args.days) },
+        });
+        if (result.status >= 400)
+            return apiResult(result);
+        return jsonResult(compactGraph(result.body));
+    }
+    if (name === "amem_status") {
+        if (workspace && !getRepoByName(workspace)) {
+            return textResult(`Workspace not found: ${workspace}`, true);
+        }
+        const result = api("GET", "/api/status", null, { workspace });
+        return apiResult(result);
+    }
+    return textResult(`Unknown tool: ${name}`, true);
+}
+function rpcResult(id, result) {
+    return { jsonrpc: "2.0", id, result };
+}
+function rpcError(id, message, code = -32601) {
+    return { jsonrpc: "2.0", id, error: { code, message } };
+}
+export function isJsonRpcMessage(body) {
+    if (!body || typeof body !== "object" || Array.isArray(body))
+        return false;
+    const msg = body;
+    return msg.jsonrpc === "2.0";
+}
+/** Handle one JSON-RPC message. Notifications (no id) return null. */
+export function dispatchMcp(msg, fallbackWorkspace) {
+    const { id, method, params } = msg;
+    if (!method)
+        return null;
+    if (id === undefined || id === null)
+        return null;
+    if (method === "initialize") {
+        const requested = params && typeof params.protocolVersion === "string" ? params.protocolVersion : "";
+        return rpcResult(id, {
+            protocolVersion: PROTOCOL_VERSIONS.has(requested) ? requested : "2024-11-05",
+            capabilities: {
+                tools: { listChanged: false },
+                resources: { listChanged: false },
+                prompts: { listChanged: false },
+            },
+            serverInfo: { name: "amem", version: "0.1.0" },
+        });
+    }
+    if (method === "ping")
+        return rpcResult(id, {});
+    if (method === "tools/list") {
+        return rpcResult(id, { tools: TOOLS });
+    }
+    if (method === "resources/list")
+        return rpcResult(id, { resources: [] });
+    if (method === "prompts/list")
+        return rpcResult(id, { prompts: [] });
+    if (method === "tools/call") {
+        const name = typeof params?.name === "string" ? params.name : "";
+        const args = params?.arguments && typeof params.arguments === "object"
+            ? params.arguments
+            : {};
+        return rpcResult(id, callTool(name, args, fallbackWorkspace));
+    }
+    return rpcError(id, `Method not found: ${method}`);
+}
+export function handleMcpHttpBody(body, fallbackWorkspace) {
+    if (Array.isArray(body)) {
+        const results = body
+            .filter(isJsonRpcMessage)
+            .map((msg) => dispatchMcp(msg, fallbackWorkspace))
+            .filter((r) => r !== null);
+        return { status: 200, body: results };
+    }
+    if (!isJsonRpcMessage(body)) {
+        return {
+            status: 400,
+            body: { jsonrpc: "2.0", error: { code: -32600, message: "Invalid JSON-RPC" } },
+        };
+    }
+    const result = dispatchMcp(body, fallbackWorkspace);
+    if (!result)
+        return { status: 202, body: null };
+    return { status: 200, body: result };
+}
+function encodeMessage(msg, framing) {
+    const payload = Buffer.from(JSON.stringify(msg), "utf8");
+    if (framing === "ndjson") {
+        return Buffer.concat([payload, Buffer.from("\n")]);
+    }
+    const header = Buffer.from(`Content-Length: ${payload.length}\r\n\r\n`, "utf8");
+    return Buffer.concat([header, payload]);
+}
+function headerEndIndex(buf) {
+    const crlf = buf.indexOf("\r\n\r\n");
+    if (crlf !== -1)
+        return { index: crlf, size: 4 };
+    const lf = buf.indexOf("\n\n");
+    if (lf !== -1)
+        return { index: lf, size: 2 };
+    return null;
+}
+function looksLikeJsonStart(buf) {
+    for (let i = 0; i < buf.length; i++) {
+        const c = buf[i];
+        if (c === 0x20 || c === 0x09 || c === 0x0a || c === 0x0d)
+            continue;
+        return c === 0x7b; // {
+    }
+    return false;
+}
+function parseStdio(buf) {
+    const items = [];
+    let rest = buf;
+    while (rest.length) {
+        if (looksLikeJsonStart(rest)) {
+            const nl = rest.indexOf("\n");
+            if (nl === -1)
+                break;
+            const line = rest.slice(0, nl).toString("utf8").trim();
+            rest = rest.slice(nl + 1);
+            if (!line)
+                continue;
+            try {
+                items.push({ msg: JSON.parse(line), framing: "ndjson" });
+            }
+            catch {
+                // skip malformed line
+            }
+            continue;
+        }
+        const headerEnd = headerEndIndex(rest);
+        if (!headerEnd)
+            break;
+        const header = rest.slice(0, headerEnd.index).toString("utf8");
+        const lenMatch = /Content-Length:\s*(\d+)/i.exec(header);
+        if (!lenMatch) {
+            rest = rest.slice(headerEnd.index + headerEnd.size);
+            continue;
+        }
+        const len = Number(lenMatch[1]);
+        const start = headerEnd.index + headerEnd.size;
+        if (rest.length < start + len)
+            break;
+        const raw = rest.slice(start, start + len).toString("utf8");
+        rest = rest.slice(start + len);
+        try {
+            items.push({ msg: JSON.parse(raw), framing: "lsp" });
+        }
+        catch {
+            // skip malformed
+        }
+    }
+    return { rest, items };
+}
+export function stdioMcpLaunch(workspace) {
+    const script = process.argv[1];
+    const useNode = Boolean(script && existsSync(script));
+    return {
+        command: useNode ? process.execPath : "amem",
+        args: useNode ? [script, "mcp"] : ["mcp"],
+        env: workspace ? { AMEM_WORKSPACE: workspace } : {},
+    };
+}
+export function mcpClientConfig(workspace = "my-app", port = 7843) {
+    const stdio = stdioMcpLaunch(workspace);
+    const httpUrl = `http://127.0.0.1:${port}/mcp?workspace=${encodeURIComponent(workspace)}`;
+    return {
+        mcpServers: {
+            amem: {
+                command: stdio.command,
+                args: stdio.args,
+                env: stdio.env,
+            },
+        },
+        http: { url: httpUrl },
+    };
+}
+export async function runMcpServer() {
+    let buf = Buffer.alloc(0);
+    let framing = "ndjson";
+    for await (const chunk of process.stdin) {
+        buf = Buffer.concat([buf, Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)]);
+        const parsed = parseStdio(buf);
+        buf = Buffer.from(parsed.rest);
+        for (const item of parsed.items) {
+            framing = item.framing;
+            const response = dispatchMcp(item.msg);
+            if (response)
+                process.stdout.write(encodeMessage(response, framing));
+        }
+    }
+}

package/dist/paths.d.ts

@@ -0,0 +1,11 @@
+export declare function tryEnsureDir(dir: string): {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+};
+/** Memory is in SQLite. A missing placeholder folder must not block workspace create. */
+export declare function amemHomeWriteIssue(): string | null;
+export declare function amemHome(): string;
+export declare function ensureAmemHome(): string;
+export declare function dbPath(): string;

package/dist/paths.js

@@ -0,0 +1,55 @@
+import { chmodSync, existsSync, mkdirSync, rmdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+export function tryEnsureDir(dir) {
+    try {
+        mkdirSync(dir, { recursive: true });
+        return { ok: true };
+    }
+    catch (error) {
+        const err = error;
+        if (err.code === "EPERM" || err.code === "EACCES") {
+            return { ok: false, message: err.message };
+        }
+        throw error;
+    }
+}
+/** Memory is in SQLite. A missing placeholder folder must not block workspace create. */
+export function amemHomeWriteIssue() {
+    const probe = join(amemHome(), "workspaces", `.write-probe-${process.pid}`);
+    try {
+        mkdirSync(probe, { recursive: true });
+        rmdirSync(probe);
+        return null;
+    }
+    catch (error) {
+        const err = error;
+        if (err.code === "EPERM" || err.code === "EACCES") {
+            return "Cannot create folders under ~/.amem (this process is likely sandboxed — e.g. amem ui started from Cursor). Quit it and run `amem ui` in Terminal, or `amem service install` so it starts at login.";
+        }
+        return null;
+    }
+}
+export function amemHome() {
+    return process.env.AMEM_HOME ?? join(homedir(), ".amem");
+}
+export function ensureAmemHome() {
+    const home = amemHome();
+    if (!existsSync(home)) {
+        mkdirSync(home, { recursive: true, mode: 0o700 });
+    }
+    try {
+        chmodSync(home, 0o700);
+    }
+    catch {
+        // Best-effort on platforms that ignore chmod
+    }
+    const sessions = join(home, "sessions");
+    if (!existsSync(sessions)) {
+        mkdirSync(sessions, { recursive: true, mode: 0o700 });
+    }
+    return home;
+}
+export function dbPath() {
+    return join(ensureAmemHome(), "graph.db");
+}

package/dist/personal.d.ts

@@ -0,0 +1,7 @@
+import { type ClaimRow, type RepoRow } from "./db.js";
+export declare const PERSONAL_SLUG = "personal";
+export declare function personalRoot(): string;
+export declare function ensurePersonalWorkspace(platform?: string): RepoRow;
+export declare function isPersonalRepo(repo: RepoRow | null | undefined): boolean;
+/** Active personal claims for blending into another repo's context. */
+export declare function listPersonalClaims(): ClaimRow[];

package/dist/personal.js

@@ -0,0 +1,44 @@
+import { join } from "node:path";
+import { applyProposal } from "./proposal.js";
+import { getRepoByName, listClaims, upsertRepo, } from "./db.js";
+import { amemHome, tryEnsureDir } from "./paths.js";
+import { workspaceIdentity } from "./repo-identity.js";
+export const PERSONAL_SLUG = "personal";
+export function personalRoot() {
+    const dir = join(amemHome(), "workspaces", PERSONAL_SLUG);
+    tryEnsureDir(dir);
+    return dir;
+}
+export function ensurePersonalWorkspace(platform = "app") {
+    const existing = getRepoByName(PERSONAL_SLUG);
+    if (existing)
+        return existing;
+    const identity = workspaceIdentity(PERSONAL_SLUG, personalRoot());
+    // Force display name
+    identity.repoName = "Personal prefs";
+    const repo = upsertRepo(identity, platform);
+    applyProposal(repo.id, {
+        claims: [
+            {
+                id: "claim.personal_scope",
+                kind: "structure",
+                text: "This is your cross-repo personal amem space (how you work). It can inject into any project context without becoming a shared company wiki.",
+                code_anchors: [PERSONAL_SLUG],
+                source_ref: "personal-setup",
+            },
+        ],
+    });
+    return getRepoByName(PERSONAL_SLUG) ?? repo;
+}
+export function isPersonalRepo(repo) {
+    if (!repo)
+        return false;
+    return (repo.remote_url || "").includes(`amem://workspace/${PERSONAL_SLUG}`) || repo.repo_name === PERSONAL_SLUG;
+}
+/** Active personal claims for blending into another repo's context. */
+export function listPersonalClaims() {
+    const personal = getRepoByName(PERSONAL_SLUG);
+    if (!personal)
+        return [];
+    return listClaims(personal.id);
+}

package/dist/platforms.d.ts

@@ -0,0 +1,11 @@
+export type KnownPlatform = {
+    id: string;
+    label: string;
+    hint: string;
+    installs?: "cursor" | "claude" | "host";
+};
+/** Clients the Setup picker can record. Cursor/Claude also get local installers. */
+export declare const KNOWN_PLATFORMS: KnownPlatform[];
+export declare function isKnownPlatform(id: string): boolean;
+export declare function normalizePlatforms(raw: unknown): string[];
+export declare const HOST_INSTALL_IDS: Set<string>;

package/dist/platforms.js

@@ -0,0 +1,32 @@
+/** Clients the Setup picker can record. Cursor/Claude also get local installers. */
+export const KNOWN_PLATFORMS = [
+    { id: "cursor", label: "Cursor", hint: "Rules, skills, hooks", installs: "cursor" },
+    { id: "claude", label: "Claude Code", hint: "Skills and settings hooks", installs: "claude" },
+    { id: "copilot", label: "GitHub Copilot", hint: "MCP / HTTP API" },
+    { id: "codex", label: "ChatGPT / Codex", hint: "MCP / HTTP API" },
+    { id: "gemini", label: "Gemini", hint: "MCP / HTTP API" },
+    { id: "windsurf", label: "Windsurf", hint: "MCP config installer", installs: "host" },
+    { id: "continue", label: "Continue", hint: "MCP config installer", installs: "host" },
+    { id: "aider", label: "Aider", hint: "CLI hint file in repo", installs: "host" },
+    { id: "zed", label: "Zed", hint: "context_servers MCP", installs: "host" },
+    { id: "grok", label: "Grok", hint: "MCP / HTTP API" },
+];
+const KNOWN_IDS = new Set(KNOWN_PLATFORMS.map((p) => p.id));
+export function isKnownPlatform(id) {
+    return KNOWN_IDS.has(id);
+}
+export function normalizePlatforms(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const value of raw) {
+        if (typeof value !== "string")
+            continue;
+        const id = value.trim().toLowerCase();
+        if (!KNOWN_IDS.has(id) || out.includes(id))
+            continue;
+        out.push(id);
+    }
+    return out;
+}
+export const HOST_INSTALL_IDS = new Set(KNOWN_PLATFORMS.filter((p) => p.installs === "host").map((p) => p.id));

package/dist/policy.d.ts

@@ -0,0 +1,46 @@
+export type AmemPolicy = {
+    telemetry: boolean;
+    ui_enabled: boolean;
+    ui_bind: string;
+    allow_export: boolean;
+    allowed_platforms: string[];
+    allowed_remote_hosts: string[];
+    deny_claim_patterns: string[];
+    /** Draft kinds that may auto-apply without Memory approve (still local). */
+    auto_apply_kinds: string[];
+};
+export type PolicySource = {
+    path: string;
+    role: "defaults" | "user" | "system" | "env";
+    applied: boolean;
+    error?: string;
+};
+export type LoadedPolicy = {
+    policy: AmemPolicy;
+    sources: PolicySource[];
+};
+/** Built-in secret hygiene — always active; policy patterns extend these. */
+export declare const BUILTIN_DENY_CLAIM_PATTERNS: string[];
+export declare const DEFAULT_POLICY: AmemPolicy;
+export declare function clearPolicyCache(): void;
+export declare function systemPolicyPath(): string;
+export declare function userPolicyPath(): string;
+/**
+ * Minimal TOML subset for amem policy files:
+ * booleans, quoted strings, and string arrays. Comments (#) and blank lines ok.
+ */
+export declare function parsePolicyToml(raw: string): Partial<AmemPolicy>;
+/**
+ * Load effective policy.
+ * Precedence (later wins): defaults → user (~/.amem) → system (/etc/amem) → AMEM_POLICY_PATH.
+ * MDM/system always overrides user for enterprise lock-down.
+ */
+export declare function loadPolicy(forceReload?: boolean): LoadedPolicy;
+export declare function effectiveDenyPatterns(policy?: AmemPolicy): string[];
+export declare function compiledDenyPatterns(policy?: AmemPolicy): RegExp[];
+export declare function assertPlatformAllowed(platform: string, policy?: AmemPolicy): void;
+export declare function assertRemoteAllowed(remoteUrl: string | null, policy?: AmemPolicy): void;
+export declare function assertExportAllowed(policy?: AmemPolicy): void;
+export declare function assertUiAllowed(policy?: AmemPolicy): void;
+/** Unused today — kept so attest / docs can prove the knob exists and is forced off. */
+export declare function telemetryEnabled(policy?: AmemPolicy): boolean;