mem-os-python 1.6.27__py3-none-any.whl

memos/_js/adapters/openai.js

@@ -0,0 +1,342 @@
+/**
+ * MemOS OpenAI Adapter — first-class memory integration for the OpenAI SDK.
+ *
+ * Wraps a MemOS instance and exposes helpers that map cleanly onto the
+ * OpenAI Chat Completions API: a memory-backed function tool, system-prompt
+ * context injection, automatic fact extraction from conversations, and
+ * simple store/forget helpers.
+ *
+ * The adapter has **zero hard dependencies** on the `openai` package. Every
+ * exported message/tool shape is structurally compatible with the
+ * corresponding `openai` types (`ChatCompletionMessageParam`,
+ * `ChatCompletionTool`, `ChatCompletionToolMessageParam`), so they can be
+ * passed straight into `openai.chat.completions.create(...)` with no glue
+ * layer. Install `openai` only if you want to call the model; the adapter
+ * itself only needs MemOS.
+ *
+ * @example
+ * ```ts
+ * import OpenAI from "openai";
+ * import { createOpenAIMemory } from "@mem-os/sdk/openai";
+ *
+ * const { plugin } = await createOpenAIMemory({ dbPath: "./my-app.db" });
+ * const openai = new OpenAI();
+ *
+ * const completion = await openai.chat.completions.create({
+ *   model: "gpt-4o",
+ *   messages: [{ role: "user", content: "What theme do I like?" }],
+ *   tools: [plugin.memoryTool],
+ * });
+ * ```
+ *
+ * @module @memos/adapters/openai
+ */
+import { MemOS } from "../index.js";
+// ---------------------------------------------------------------------------
+// Plugin
+// ---------------------------------------------------------------------------
+/**
+ * OpenAI SDK memory plugin backed by MemOS.
+ *
+ * Wrap an existing MemOS instance, or use {@link createOpenAIMemory} to
+ * construct both in one call. The plugin does not call the OpenAI API
+ * itself — it prepares memories (as tools, tool messages, and system-prompt
+ * strings) for you to feed into your own `openai.chat.completions` calls.
+ */
+export class MemOSOpenAIPlugin {
+    /** The wrapped MemOS instance. */
+    memos;
+    opts;
+    /**
+     * Create a new OpenAI memory plugin.
+     *
+     * @param memos - An initialised MemOS instance.
+     * @param opts  - Plugin options. All fields optional with sensible defaults.
+     */
+    constructor(memos, opts = {}) {
+        this.memos = memos;
+        this.opts = {
+            maxContextMemories: opts.maxContextMemories ?? 5,
+            autoExtractFacts: opts.autoExtractFacts ?? true,
+            minMessageLength: opts.minMessageLength ?? 15,
+            source: opts.source ?? "user_input",
+            minConfidence: opts.minConfidence ?? 0.6,
+            namespace: opts.namespace ?? "default",
+        };
+    }
+    /**
+     * OpenAI function-tool definition that lets the model search the user's
+     * memory. Pass it via the `tools` parameter of
+     * `openai.chat.completions.create`.
+     *
+     * When the model invokes it, call {@link searchMemories} and return the
+     * `toolMessage` field (after setting `tool_call_id`) as a tool message.
+     */
+    get memoryTool() {
+        return {
+            type: "function",
+            function: {
+                name: "search_memories",
+                description: "Search the user's persistent MemOS memory for relevant facts, " +
+                    "preferences, and context. Call this before answering personal or " +
+                    "preference questions, or when prior context seems relevant.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        query: {
+                            type: "string",
+                            description: "Natural-language search query.",
+                        },
+                        limit: {
+                            type: "number",
+                            description: "Maximum number of memories to return.",
+                            default: 5,
+                        },
+                    },
+                    required: ["query"],
+                },
+            },
+        };
+    }
+    /**
+     * Extract facts from a conversation and store them in MemOS.
+     *
+     * Runs MemOS' local rule-based fact extractor over the conversation,
+     * persisting any candidate facts whose confidence meets the configured
+     * `minConfidence` threshold. Near-duplicates are skipped automatically
+     * when embeddings are available.
+     *
+     * @param conversation - The messages to extract facts from.
+     * @returns The extraction result (candidate facts, stored ids, dup count).
+     */
+    async addMessages(conversation) {
+        const candidates = conversation.filter((m) => m.content.trim().length >= this.opts.minMessageLength);
+        if (candidates.length === 0) {
+            return { facts: [], storedIds: [], duplicates: 0 };
+        }
+        return this.memos.extractFacts(candidates, {
+            autoStore: true,
+            minConfidence: this.opts.minConfidence,
+            namespace: this.opts.namespace,
+            dedupe: true,
+        });
+    }
+    /**
+     * Search memories and format the results for OpenAI tool use.
+     *
+     * @param query - Natural-language search query.
+     * @param opts  - Search options (limit, type, namespace).
+     * @returns An object containing the ranked memory entries and a
+     *   ready-to-send `tool` message (JSON-encoded memories). Set
+     *   `toolMessage.tool_call_id` to the model's `tool_call` id before
+     *   returning it.
+     */
+    async searchMemories(query, opts = {}) {
+        const filter = {
+            query,
+            limit: opts.limit ?? this.opts.maxContextMemories,
+        };
+        if (opts.type)
+            filter.type = opts.type;
+        if (opts.namespace)
+            filter.namespace = opts.namespace;
+        const results = await this.memos.search(filter);
+        const memories = results.map((r) => this.toEntry(r));
+        const content = memories.length > 0
+            ? JSON.stringify(memories, null, 2)
+            : "No relevant memories found.";
+        return {
+            query,
+            memories,
+            toolMessage: { role: "tool", content },
+        };
+    }
+    /**
+     * Build a system-prompt string of relevant memories for injection.
+     *
+     * Optionally extracts & stores facts from the recent `messages` first,
+     * then searches MemOS using the most recent user message and returns the
+     * matches as a formatted block ready to prepend to the `system` prompt.
+     *
+     * @param messages - Recent conversation messages.
+     * @param opts     - Context options (limit, whether to extract).
+     * @returns A memory-context string, or `""` if nothing relevant was found.
+     */
+    async getMemoryContext(messages, opts = {}) {
+        const shouldExtract = opts.extract ?? this.opts.autoExtractFacts;
+        if (shouldExtract && messages.length > 0) {
+            await this.addMessages(messages);
+        }
+        const lastUser = [...messages].reverse().find((m) => m.role === "user");
+        const query = lastUser?.content.trim() ?? "";
+        if (!query)
+            return "";
+        const results = await this.memos.search({
+            query,
+            limit: opts.limit ?? this.opts.maxContextMemories,
+        });
+        if (results.length === 0)
+            return "";
+        const lines = ["Relevant memories from prior conversations:"];
+        results.forEach((m, i) => {
+            lines.push(`  ${i + 1}. [${m.node.type}] ${m.node.content}`);
+        });
+        return lines.join("\n");
+    }
+    /**
+     * Manually store a memory.
+     *
+     * @param content - Text to remember.
+     * @param opts    - Additional memory parameters (type, tags, importance…).
+     * @returns The created memory node.
+     */
+    async remember(content, opts = {}) {
+        const { node } = await this.memos.store(content, {
+            ...opts,
+            source: opts.source ?? this.opts.source,
+            namespace: opts.namespace ?? this.opts.namespace,
+        });
+        return node;
+    }
+    /**
+     * Search for relevant memories.
+     *
+     * @param query - Search query.
+     * @param limit - Maximum number of results. @default 5
+     * @returns Scored memory nodes.
+     */
+    async recall(query, limit = 5) {
+        return this.memos.search({ query, limit });
+    }
+    /**
+     * Permanently forget a memory.
+     *
+     * @param memoryId - ID of the memory to delete.
+     * @returns `true` if the memory existed and was deleted.
+     */
+    async forget(memoryId) {
+        return this.memos.forget(memoryId);
+    }
+    /**
+     * Remove all memories and edges from the underlying MemOS instance.
+     *
+     * This is destructive and cannot be undone.
+     */
+    async clearMemories() {
+        await this.memos.clear();
+    }
+    /**
+     * Return the total number of stored memories.
+     *
+     * @returns The current memory count.
+     */
+    getMemoryCount() {
+        return this.memos.count;
+    }
+    /** Convert a scored memory into a JSON-friendly entry. */
+    toEntry(scored) {
+        return {
+            id: scored.node.id,
+            content: scored.node.content,
+            summary: scored.node.summary,
+            type: scored.node.type,
+            score: scored.score,
+            tags: scored.node.tags,
+            trustScore: scored.node.trustScore,
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// Convenience constructor
+// ---------------------------------------------------------------------------
+/**
+ * Create a MemOS instance and an OpenAI memory plugin in one call.
+ *
+ * The MemOS instance is created with `config`, initialised, and wrapped in a
+ * {@link MemOSOpenAIPlugin}. Plugin-level options go under `config.plugin`.
+ *
+ * @param config - MemOS config plus optional `plugin` options.
+ * @returns The initialised `memos` instance and bound `plugin`.
+ *
+ * @example
+ * ```ts
+ * const { memos, plugin } = await createOpenAIMemory({
+ *   dbPath: "./my-app.db",
+ *   plugin: { maxContextMemories: 8 },
+ * });
+ * ```
+ */
+export async function createOpenAIMemory(config = {}) {
+    const { plugin: pluginOpts, ...memosConfig } = config;
+    const memos = new MemOS(memosConfig);
+    await memos.init();
+    const plugin = new MemOSOpenAIPlugin(memos, pluginOpts);
+    return { memos, plugin };
+}
+// ---------------------------------------------------------------------------
+// Usage example
+// ---------------------------------------------------------------------------
+/*
+ * End-to-end example using the official `openai` SDK.
+ *
+ *   npm install openai
+ *
+ * import OpenAI from "openai";
+ * import { createOpenAIMemory } from "@mem-os/sdk/openai";
+ *
+ * // 1. Boot MemOS + the plugin.
+ * const { memos, plugin } = await createOpenAIMemory({
+ *   dbPath: "./my-app.db",
+ *   plugin: { maxContextMemories: 6 },
+ * });
+ *
+ * const openai = new OpenAI();
+ *
+ * // 2. Teach it something. addMessages() extracts & stores facts.
+ * await plugin.addMessages([
+ *   { role: "user", content: "I prefer dark mode in all my apps." },
+ *   { role: "assistant", content: "Got it — dark mode it is." },
+ * ]);
+ *
+ * // 3a. Context-injection style: fold memories into the system prompt.
+ * const systemCtx = await plugin.getMemoryContext([
+ *   { role: "user", content: "What theme do I like?" },
+ * ]);
+ * const a = await openai.chat.completions.create({
+ *   model: "gpt-4o",
+ *   messages: [
+ *     { role: "system", content: `You are a helpful assistant.\n\n${systemCtx}` },
+ *     { role: "user", content: "What theme do I like?" },
+ *   ],
+ * });
+ * console.log(a.choices[0].message.content); // → "dark mode"
+ *
+ * // 3b. Tool style: let the model call search_memories itself.
+ * const tools = [plugin.memoryTool];
+ * const res = await openai.chat.completions.create({
+ *   model: "gpt-4o",
+ *   messages: [{ role: "user", content: "What theme do I like?" }],
+ *   tools,
+ * });
+ * const call = res.choices[0].message.tool_calls?.[0];
+ * if (call && call.function.name === "search_memories") {
+ *   const { query } = JSON.parse(call.function.arguments);
+ *   const { toolMessage } = await plugin.searchMemories(query);
+ *   toolMessage.tool_call_id = call.id;
+ *   const followUp = await openai.chat.completions.create({
+ *     model: "gpt-4o",
+ *     messages: [
+ *       { role: "user", content: "What theme do I like?" },
+ *       res.choices[0].message,
+ *       toolMessage,
+ *     ],
+ *     tools,
+ *   });
+ *   console.log(followUp.choices[0].message.content); // → "dark mode"
+ * }
+ *
+ * // 4. Housekeeping helpers.
+ * console.log(plugin.getMemoryCount()); // number of stored memories
+ * await plugin.clearMemories();         // wipe everything
+ */
+//# sourceMappingURL=openai.js.map

memos/_js/adapters/openai.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai.js","sourceRoot":"","sources":["../../src/adapters/openai.ts"],"names":[],"mappings":"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"}

memos/_js/apps/explorer.d.ts

@@ -0,0 +1,244 @@
+/**
+ * MCP Apps memory explorer — an interactive graph UI served as a `ui://`
+ * resource (MCP Apps, ratified Jan 2026).
+ *
+ * The explorer renders the MemOS entity/memory graph as a self-contained,
+ * CSP-locked HTML payload: no external network fetches, no CDN scripts —
+ * the SVG renderer, pan/zoom, and filters are all hand-rolled in the
+ * payload. The bitemporal "as-of" scrubber re-queries the graph at any past
+ * timestamp through the host: each scrub position sends a structured `read`
+ * request over the `postMessage` bridge, the host performs a server-side
+ * `resources/read` at that timestamp (the existing as-of read path), and the
+ * app swaps in the returned snapshot. Nodes are colored by provenance
+ * tier, edges labeled by relation type.
+ *
+ * Consent model (the important part): the app itself is UNPRIVILEGED. It
+ * cannot touch the database. Mutating actions (forget, link, release from
+ * quarantine) are expressed as structured *intents* posted to the host via
+ * `postMessage`; the host translates each intent into a normal MCP
+ * `tools/call` (see {@link intentToToolCall}) so the HOST's consent UI
+ * applies exactly as if the agent had called the tool itself. Read-path
+ * interactions (pan/zoom/filter/scrub) need no consent.
+ *
+ * Where the host has no MCP Apps support the same resource serves a
+ * text/markdown fallback (mermaid diagram + summary) instead of the HTML
+ * app — see {@link resolveExplorerMode}.
+ *
+ * Everything here is deterministic and LLM-free.
+ *
+ * @module @mem-os/apps-explorer
+ */
+import { UriTemplate, type Variables } from "@modelcontextprotocol/server";
+import type { GraphSnapshot, MemoryEdge, MemoryNode, ProvenanceTier } from "../types.js";
+/** Canonical resource URI for the explorer app. */
+export declare const EXPLORER_APP_URI = "ui://memos/explorer";
+/**
+ * URI template registered on the MCP server. Query variables:
+ * - `asOf`      — unix ms; render the graph as of a past timestamp
+ *                 (bitemporal time-travel) instead of live.
+ * - `mode`      — `app` forces the HTML app, `text` forces the markdown
+ *                 fallback. Unset: auto-detect from the host signal,
+ *                 defaulting to the safe `text` fallback.
+ * - `nodeLimit` — override the node cap (clamped to 1..1000).
+ * - `edgeLimit` — override the edge cap (clamped to 1..2000).
+ */
+export declare const EXPLORER_URI_TEMPLATE = "ui://memos/explorer{?asOf,mode,nodeLimit,edgeLimit}";
+/**
+ * URI template for the explorer resource with correct optional-query
+ * matching.
+ *
+ * The SDK's built-in `UriTemplate.match()` compiles `{?a,b,...}` into a
+ * regex that requires *every* variable to be present, in declaration order —
+ * so `ui://memos/explorer?mode=app` would never match
+ * `ui://memos/explorer{?asOf,mode,nodeLimit,edgeLimit}`. This subclass keeps
+ * the standard template string (so `resources/templates/list` advertises the
+ * documented template) but overrides matching: the path must be exactly
+ * `ui://memos/explorer`, and any subset of the documented query parameters
+ * may be present, in any order. Unknown query parameters are ignored.
+ */
+export declare class ExplorerUriTemplate extends UriTemplate {
+    constructor();
+    match(uri: string): Variables | null;
+}
+/** Default cap on nodes embedded in one payload (keeps it small). */
+export declare const EXPLORER_NODE_CAP = 150;
+/** Default cap on edges embedded in one payload. */
+export declare const EXPLORER_EDGE_CAP = 400;
+/** Hard ceiling for client-overridden caps. */
+export declare const EXPLORER_NODE_CAP_MAX = 1000;
+export declare const EXPLORER_EDGE_CAP_MAX = 2000;
+/** Characters of node content embedded per node. */
+export declare const EXPLORER_CONTENT_CHARS = 280;
+/**
+ * postMessage protocol identifier. The app posts
+ * `{ protocol: "memos-explorer/1", kind: "intent", intent, params, requestId }`
+ * to `window.parent`; hosts translate intents via {@link intentToToolCall}
+ * and reply with `{ protocol: "memos-explorer/1", kind: "intent-result", ... }`.
+ *
+ * Read-path time travel uses a second message pair so scrubbing the as-of
+ * slider re-queries the server instead of filtering the embedded snapshot
+ * client-side: the app posts
+ * `{ protocol: "memos-explorer/1", kind: "read", requestId, asOf: number|null }`
+ * (`asOf: null` = live graph) and the host performs an MCP `resources/read`
+ * of `ui://memos/explorer?mode=app` (plus `&asOf=<ms>` when set) and replies
+ * with `{ protocol: "memos-explorer/1", kind: "snapshot", requestId, ok, html?, error? }`
+ * where `html` is the raw resource text — the app extracts the new snapshot
+ * from its `<script id="memos-snapshot">` tag and re-renders. Reads need no
+ * consent. If the host never answers (no bridge support) the app falls back
+ * to filtering its embedded snapshot locally.
+ */
+export declare const EXPLORER_PROTOCOL = "memos-explorer/1";
+/** Node fill color per provenance tier (highest trust → greenest). */
+export declare const PROVENANCE_TIER_COLORS: Record<ProvenanceTier, string>;
+/** Edge stroke color per relation type. */
+export declare const EDGE_RELATION_COLORS: Record<string, string>;
+/** Intents the app may emit (all go through host consent). */
+export declare const SUPPORTED_INTENTS: readonly ["forget", "link", "release-quarantine"];
+export type ExplorerIntentName = (typeof SUPPORTED_INTENTS)[number];
+/** Compact, JSON-safe node projection embedded in the app payload. */
+export interface ExplorerNode {
+    id: string;
+    content: string;
+    contentTruncated: boolean;
+    type: string;
+    importance: number;
+    trustScore: number;
+    /** Provenance tier string; "unknown" when the row predates the column. */
+    provenance: string;
+    quarantined: boolean;
+    quarantineReason: string | null;
+    validFrom: number | null;
+    validTo: number | null;
+    createdAt: number;
+    /** Citable `[mem:hex]` token for this memory. */
+    citation: string;
+}
+/** Compact, JSON-safe edge projection embedded in the app payload. */
+export interface ExplorerEdge {
+    id: string;
+    sourceId: string;
+    targetId: string;
+    relation: string;
+    weight: number;
+    validFrom: number | null;
+    validTo: number | null;
+}
+/** Everything the app needs, in one JSON blob. */
+export interface ExplorerSnapshot {
+    nodes: ExplorerNode[];
+    edges: ExplorerEdge[];
+    /** Pre-cap totals, so the UI can say "showing 150 of 1,204". */
+    totalNodes: number;
+    totalEdges: number;
+    truncated: boolean;
+    /** When the snapshot was generated (unix ms). */
+    generatedAt: number;
+    /** As-of timestamp when rendered for a past moment, else null (live). */
+    asOf: number | null;
+}
+export interface SnapshotOptions {
+    nodeCap?: number;
+    edgeCap?: number;
+    /** Pre-filter to this bitemporal timestamp (unix ms). */
+    asOf?: number;
+}
+/**
+ * Build the capped, JSON-safe snapshot the app embeds. Nodes are taken in
+ * importance order (most important first); edges are kept only when both
+ * endpoints survived the node cap, in weight order. Pass `asOf` to
+ * pre-filter to a bitemporal timestamp (same predicates as the server
+ * as-of read path).
+ */
+export declare function buildExplorerSnapshot(graph: GraphSnapshot, opts?: SnapshotOptions): ExplorerSnapshot;
+/**
+ * Node as-of predicate — identical to the SQLite as-of read path
+ * (`valid_from <= t AND (valid_to IS NULL OR valid_to >= t)`).
+ */
+export declare function isNodeValidAt(node: Pick<MemoryNode, "validFrom" | "validTo"> | Pick<ExplorerNode, "validFrom" | "validTo">, atTime: number): boolean;
+/**
+ * Edge as-of predicate — identical to the SQLite edge as-of read path,
+ * which uses strict `valid_to > t` (see `queryEdges({ validAt })`): an
+ * edge closed in the same millisecond as the query is already historical.
+ */
+export declare function isEdgeValidAt(edge: Pick<MemoryEdge, "validFrom" | "validTo"> | Pick<ExplorerEdge, "validFrom" | "validTo">, atTime: number): boolean;
+/**
+ * The as-of scrubber's filter: re-evaluate a snapshot at a past timestamp.
+ * This is the graceful-degradation path for the time slider — the same
+ * predicates the server uses, applied client-side to the embedded
+ * snapshot — used only when the host does not implement the `read` bridge
+ * (see {@link EXPLORER_PROTOCOL}). With a supporting host, every scrub
+ * position re-queries the server via `resources/read?asOf=` instead.
+ */
+export declare function filterSnapshotAsOf(snapshot: ExplorerSnapshot, atTime: number): ExplorerSnapshot;
+export type ExplorerMode = "app" | "text";
+/**
+ * Probe a `resources/read` request `_meta` for host MCP Apps support.
+ * Returns true/false on an explicit signal, null when the host says
+ * nothing (the common case for older clients).
+ */
+export declare function probeHostAppsSupport(meta: unknown): boolean | null;
+export interface ResolveModeOptions {
+    /** Raw `mode` URI-template variable (`app` | `text`), if given. */
+    modeParam?: string | null;
+    /** The `resources/read` request `_meta` (host signal probe). */
+    meta?: unknown;
+}
+/**
+ * Decide whether to serve the HTML app or the markdown fallback.
+ *
+ * 1. An explicit `?mode=app|text` always wins.
+ * 2. Otherwise an explicit host Apps signal in `_meta` wins.
+ * 3. Otherwise fail closed to the `text` fallback: a host that cannot
+ *    render the app must never receive a raw HTML blob it would dump as
+ *    markup into the conversation.
+ */
+export declare function resolveExplorerMode(opts: ResolveModeOptions): ExplorerMode;
+export interface IntentToolCall {
+    /** MCP tool name — the host calls this via the standard tools/call path. */
+    tool: string;
+    args: Record<string, unknown>;
+}
+export type IntentTranslation = {
+    ok: true;
+    intent: ExplorerIntentName;
+    call: IntentToolCall;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Translate a UI intent (posted by the app via `postMessage`) into the MCP
+ * tool call the host must issue. Pure and zod-validated: unknown intents
+ * and malformed params are rejected here, before any host consent UI.
+ *
+ * The host — never this module, never the app — performs the actual
+ * `tools/call`, so the host's consent model applies to every mutation.
+ * The app itself has no credentials and no database access.
+ */
+export declare function intentToToolCall(raw: unknown): IntentTranslation;
+export interface FallbackOptions {
+    asOf?: number | null;
+}
+/**
+ * Build the graceful-degradation payload: the mermaid diagram (reusing
+ * `graphToMermaid`, the same renderer as `memos://graph`) plus a summary.
+ * Served when {@link resolveExplorerMode} picks `"text"`.
+ */
+export declare function buildExplorerFallbackMarkdown(snapshot: ExplorerSnapshot, opts?: FallbackOptions): string;
+export interface HtmlOptions {
+    asOf?: number | null;
+}
+/**
+ * Build the single-file HTML app payload.
+ *
+ * Security properties (asserted by tests):
+ * - `<meta http-equiv="Content-Security-Policy">` locks the document down:
+ *   no network, no plugins, inline scripts/styles only.
+ * - No external URLs anywhere in the payload (no CDNs, fonts, images).
+ * - An HTML comment states the host-side requirement:
+ *   `<iframe sandbox="allow-scripts">` (no `allow-same-origin`).
+ * - The app is unprivileged: the only outbound channel is `postMessage`
+ *   intents to the host; there is no database access from this layer.
+ */
+export declare function buildExplorerHtml(snapshot: ExplorerSnapshot, opts?: HtmlOptions): string;
+//# sourceMappingURL=explorer.d.ts.map

memos/_js/apps/explorer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explorer.d.ts","sourceRoot":"","sources":["../../src/apps/explorer.ts"],"names":[],"mappings":"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"}