mentedb 0.47.0 → 0.48.0

package/README.md

@@ -109,6 +109,23 @@ profile) is not exposed by the Node.js package; use the Python SDK or the
 server for it. `ingest` calls an LLM and needs `MENTEDB_LLM_PROVIDER`
 (`openai`, `anthropic` or `ollama`) and `MENTEDB_LLM_API_KEY`.
 
+## Claude memory tool backend
+
+`MemoryTool` backs Claude's client side memory tool (`memory_20250818`) with a
+`mentedb-server` or MenteDB Cloud over `fetch`. Each `/memories` file is a
+memory scoped to the agent:
+
+```typescript
+import { MemoryTool } from 'mentedb';
+
+const memory = new MemoryTool({ baseUrl: 'http://localhost:6677', token, agentId: '...' });
+// tools: [MemoryTool.TOOL] on the Messages API request, then each turn:
+messages.push({ role: 'user', content: await memory.results(response.content) });
+```
+
+See [the memory tool guide](../../docs/MEMORY_TOOL.md) and
+[`examples/memory_tool_agent.ts`](examples/memory_tool_agent.ts).
+
 ## API reference
 
 ### `MenteDB`

package/npm/client.d.ts

@@ -1,4 +1,4 @@
-import { EdgeType, type StoreOptions, type RecallResult, type SearchResult, type ProcessTurnResult, type IngestResult, type ErasureReceipt } from './types';
+import { EdgeType, type StoreOptions, type RecallResult, type SearchResult, type ProcessTurnResult, type IngestResult, type ErasureReceipt, type SessionErasureReceipt, type Memory, type ProvenanceFilter } from './types';
 /**
  * MenteDB client. Wraps the native Rust database engine and exposes a
  * TypeScript-friendly API for storing, recalling, searching, relating, and
@@ -28,12 +28,22 @@ export declare class MenteDB {
      * or pass `provider` ("openai", "anthropic", or "ollama") explicitly.
      */
     ingest(conversation: string, provider?: string, agentId?: string): IngestResult;
-    /** Store a memory and return its UUID. */
+    /**
+     * Store a memory and return its UUID. `sessionId`, `source` and
+     * `sourceRef` are recorded as its provenance on the first write.
+     */
     store(options: StoreOptions): string;
+    /** One stored memory with its provenance. Throws when the id is unknown. */
+    getMemory(memoryId: string): Memory;
+    /** Ids of every memory written in `sessionId`. */
+    memoryIdsInSession(sessionId: string): string[];
     /** Recall memories using an MQL query string. */
     recall(query: string): RecallResult;
-    /** Vector similarity search returning top-k results. */
-    search(embedding: number[], k?: number): SearchResult[];
+    /**
+     * Vector similarity search returning top-k results, optionally narrowed to
+     * memories written in a session and/or from a kind of source.
+     */
+    search(embedding: number[], k?: number, filter?: ProvenanceFilter): SearchResult[];
     /** Create a typed, weighted edge between two memories. */
     relate(source: string, target: string, edgeType?: EdgeType, weight?: number): void;
     /** Remove a memory by ID. */
@@ -49,6 +59,15 @@ export declare class MenteDB {
         includeSources?: boolean;
         verify?: boolean;
     }): ErasureReceipt;
+    /**
+     * Verified erase of every memory written in `sessionId` and everything
+     * derived from them, in one erase with one receipt. A session with no
+     * memories returns an empty receipt. See docs/PROVENANCE.md.
+     */
+    eraseSession(sessionId: string, options?: {
+        includeSources?: boolean;
+        verify?: boolean;
+    }): SessionErasureReceipt;
     /** Flush all data and close the database. */
     close(): void;
 }

package/npm/client.js

@@ -99,18 +99,32 @@ class MenteDB {
     ingest(conversation, provider, agentId) {
         return this.native.ingest(conversation, provider ?? null, agentId ?? null);
     }
-    /** Store a memory and return its UUID. */
+    /**
+     * Store a memory and return its UUID. `sessionId`, `source` and
+     * `sourceRef` are recorded as its provenance on the first write.
+     */
     store(options) {
-        const { content, memoryType = types_1.MemoryType.Episodic, embedding = [], agentId, tags, } = options;
-        return this.native.store(content, memoryType, embedding, agentId, tags);
+        const { content, memoryType = types_1.MemoryType.Episodic, embedding = [], agentId, tags, sessionId, source, sourceRef, } = options;
+        return this.native.store(content, memoryType, embedding, agentId, tags, sessionId ?? null, source ?? null, sourceRef ?? null);
+    }
+    /** One stored memory with its provenance. Throws when the id is unknown. */
+    getMemory(memoryId) {
+        return this.native.getMemory(memoryId);
+    }
+    /** Ids of every memory written in `sessionId`. */
+    memoryIdsInSession(sessionId) {
+        return this.native.memoryIdsInSession(sessionId);
     }
     /** Recall memories using an MQL query string. */
     recall(query) {
         return this.native.recall(query);
     }
-    /** Vector similarity search returning top-k results. */
-    search(embedding, k = 10) {
-        return this.native.search(embedding, k);
+    /**
+     * Vector similarity search returning top-k results, optionally narrowed to
+     * memories written in a session and/or from a kind of source.
+     */
+    search(embedding, k = 10, filter = {}) {
+        return this.native.search(embedding, k, filter.sessionId ?? null, filter.source ?? null);
     }
     /** Create a typed, weighted edge between two memories. */
     relate(source, target, edgeType = types_1.EdgeType.Related, weight = 1.0) {
@@ -131,6 +145,15 @@ class MenteDB {
         const json = this.native.erase(memoryId, options.includeSources, options.verify);
         return JSON.parse(json);
     }
+    /**
+     * Verified erase of every memory written in `sessionId` and everything
+     * derived from them, in one erase with one receipt. A session with no
+     * memories returns an empty receipt. See docs/PROVENANCE.md.
+     */
+    eraseSession(sessionId, options = {}) {
+        const json = this.native.eraseSession(sessionId, options.includeSources, options.verify);
+        return JSON.parse(json);
+    }
     /** Flush all data and close the database. */
     close() {
         this.native.close();

package/npm/index.d.ts

@@ -1,3 +1,5 @@
 export { MenteDB, CognitionStream, TrajectoryTracker } from './client';
 export { MemoryType, EdgeType } from './types';
-export type { RecallResult, SearchResult, StoreOptions, ErasureReceipt } from './types';
+export type { RecallResult, SearchResult, StoreOptions, ErasureReceipt, SessionErasureReceipt, ErasureOutcome, Memory, Provenance, ProvenanceFilter, } from './types';
+export { MemoryTool, MemoryToolError, MEMORY_TOOL_DEFINITION, DEFAULT_SERVER_URL } from './memoryTool';
+export type { MemoryToolInput, MemoryToolResult, MemoryToolResultBlock, MemoryToolOptions, } from './memoryTool';

package/npm/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EdgeType = exports.MemoryType = exports.TrajectoryTracker = exports.CognitionStream = exports.MenteDB = void 0;
+exports.DEFAULT_SERVER_URL = exports.MEMORY_TOOL_DEFINITION = exports.MemoryToolError = exports.MemoryTool = exports.EdgeType = exports.MemoryType = exports.TrajectoryTracker = exports.CognitionStream = exports.MenteDB = void 0;
 var client_1 = require("./client");
 Object.defineProperty(exports, "MenteDB", { enumerable: true, get: function () { return client_1.MenteDB; } });
 Object.defineProperty(exports, "CognitionStream", { enumerable: true, get: function () { return client_1.CognitionStream; } });
@@ -8,3 +8,8 @@ Object.defineProperty(exports, "TrajectoryTracker", { enumerable: true, get: fun
 var types_1 = require("./types");
 Object.defineProperty(exports, "MemoryType", { enumerable: true, get: function () { return types_1.MemoryType; } });
 Object.defineProperty(exports, "EdgeType", { enumerable: true, get: function () { return types_1.EdgeType; } });
+var memoryTool_1 = require("./memoryTool");
+Object.defineProperty(exports, "MemoryTool", { enumerable: true, get: function () { return memoryTool_1.MemoryTool; } });
+Object.defineProperty(exports, "MemoryToolError", { enumerable: true, get: function () { return memoryTool_1.MemoryToolError; } });
+Object.defineProperty(exports, "MEMORY_TOOL_DEFINITION", { enumerable: true, get: function () { return memoryTool_1.MEMORY_TOOL_DEFINITION; } });
+Object.defineProperty(exports, "DEFAULT_SERVER_URL", { enumerable: true, get: function () { return memoryTool_1.DEFAULT_SERVER_URL; } });

package/npm/memoryTool.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Backend for the client side memory tool (`memory_20250818`), stored in MenteDB.
+ *
+ * The model sends file style commands (`view`, `create`, `str_replace`,
+ * `insert`, `delete`, `rename`) against a `/memories` directory. Your tool
+ * loop forwards each `tool_use` input to `POST /v1/memory_tool` and copies the
+ * reply into a `tool_result` block. `MemoryTool` does both steps. A
+ * self-hosted `mentedb-server` and MenteDB Cloud serve the same contract, so
+ * only the base URL and credential change.
+ *
+ * Uses the global `fetch` (Node 18+) and loads no native code, so it can be
+ * imported on its own: `import { MemoryTool } from 'mentedb/npm/memoryTool'`.
+ */
+/** Default address of a self-hosted `mentedb-server`. */
+export declare const DEFAULT_SERVER_URL = "http://localhost:6677";
+/** Tool definition to pass in `tools` on a Messages API request. */
+export declare const MEMORY_TOOL_DEFINITION: {
+    readonly type: "memory_20250818";
+    readonly name: "memory";
+};
+/** The input of a memory `tool_use` block. */
+export interface MemoryToolInput {
+    command: 'view' | 'create' | 'str_replace' | 'insert' | 'delete' | 'rename' | string;
+    path?: string;
+    view_range?: number[];
+    file_text?: string;
+    old_str?: string;
+    new_str?: string;
+    insert_line?: number;
+    insert_text?: string;
+    old_path?: string;
+    new_path?: string;
+}
+/** What the server returns for one command. */
+export interface MemoryToolResult {
+    content: string;
+    is_error: boolean;
+}
+/** A `tool_result` content block, ready to send back in a user message. */
+export interface MemoryToolResultBlock {
+    type: 'tool_result';
+    tool_use_id: string;
+    content: string;
+    is_error?: boolean;
+}
+/** The parts of an assistant content block this helper reads. */
+export interface ContentBlockLike {
+    type: string;
+    id?: string;
+    name?: string;
+    input?: unknown;
+}
+export interface MemoryToolOptions {
+    /** e.g. `http://localhost:6677` (self-hosted) or `https://api.mentedb.com` (cloud). */
+    baseUrl?: string;
+    /** Bearer token: a server JWT, or an `mdb_` key for the cloud. Unset for a server without auth. */
+    token?: string;
+    /** A named database on a self-hosted server. Unset uses the default database. */
+    database?: string;
+    /**
+     * Whose files to act on. A token bound to an agent always acts as that
+     * agent; this is for unbound or admin tokens and servers without auth.
+     */
+    agentId?: string;
+    /** Optionally split one agent's files further by user. */
+    userId?: string;
+    /** Per request timeout in milliseconds. Default 30000. */
+    timeoutMs?: number;
+    /** A `fetch` implementation. Defaults to the global one. */
+    fetch?: typeof fetch;
+}
+/** Auth, transport and server failures. Command failures are results, not errors. */
+export declare class MemoryToolError extends Error {
+    readonly status?: number;
+    constructor(message: string, status?: number);
+}
+/** Runs memory tool calls against a MenteDB server. */
+export declare class MemoryTool {
+    /** Tool definition to pass in `tools` on a Messages API request. */
+    static readonly TOOL: {
+        readonly type: "memory_20250818";
+        readonly name: "memory";
+    };
+    readonly url: string;
+    private readonly token?;
+    private readonly agentId?;
+    private readonly userId?;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    constructor(options?: MemoryToolOptions);
+    /**
+     * Run one command. Command failures the model can fix (a missing file, a
+     * bad range, an invalid path) come back with `is_error` set; auth and
+     * server failures throw `MemoryToolError`.
+     */
+    execute(input: MemoryToolInput | Record<string, unknown>): Promise<MemoryToolResult>;
+    /** Turn one memory `tool_use` block into its `tool_result` block. */
+    handle(toolUse: ContentBlockLike): Promise<MemoryToolResultBlock>;
+    /**
+     * `tool_result` blocks for every memory call in an assistant turn. Pass
+     * `response.content`; other blocks are skipped. Send all results in one
+     * user message.
+     */
+    results(content: ReadonlyArray<ContentBlockLike>): Promise<MemoryToolResultBlock[]>;
+}

package/npm/memoryTool.js

@@ -0,0 +1,119 @@
+"use strict";
+/**
+ * Backend for the client side memory tool (`memory_20250818`), stored in MenteDB.
+ *
+ * The model sends file style commands (`view`, `create`, `str_replace`,
+ * `insert`, `delete`, `rename`) against a `/memories` directory. Your tool
+ * loop forwards each `tool_use` input to `POST /v1/memory_tool` and copies the
+ * reply into a `tool_result` block. `MemoryTool` does both steps. A
+ * self-hosted `mentedb-server` and MenteDB Cloud serve the same contract, so
+ * only the base URL and credential change.
+ *
+ * Uses the global `fetch` (Node 18+) and loads no native code, so it can be
+ * imported on its own: `import { MemoryTool } from 'mentedb/npm/memoryTool'`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryTool = exports.MemoryToolError = exports.MEMORY_TOOL_DEFINITION = exports.DEFAULT_SERVER_URL = void 0;
+/** Default address of a self-hosted `mentedb-server`. */
+exports.DEFAULT_SERVER_URL = 'http://localhost:6677';
+/** Tool definition to pass in `tools` on a Messages API request. */
+exports.MEMORY_TOOL_DEFINITION = { type: 'memory_20250818', name: 'memory' };
+/** Auth, transport and server failures. Command failures are results, not errors. */
+class MemoryToolError extends Error {
+    constructor(message, status) {
+        super(message);
+        this.name = 'MemoryToolError';
+        this.status = status;
+    }
+}
+exports.MemoryToolError = MemoryToolError;
+/** Runs memory tool calls against a MenteDB server. */
+class MemoryTool {
+    constructor(options = {}) {
+        const base = (options.baseUrl ?? exports.DEFAULT_SERVER_URL).replace(/\/+$/, '');
+        this.url = options.database
+            ? `${base}/v1/db/${encodeURIComponent(options.database)}/memory_tool`
+            : `${base}/v1/memory_tool`;
+        this.token = options.token;
+        this.agentId = options.agentId;
+        this.userId = options.userId;
+        this.timeoutMs = options.timeoutMs ?? 30000;
+        this.fetchImpl = options.fetch ?? fetch;
+    }
+    /**
+     * Run one command. Command failures the model can fix (a missing file, a
+     * bad range, an invalid path) come back with `is_error` set; auth and
+     * server failures throw `MemoryToolError`.
+     */
+    async execute(input) {
+        const body = {};
+        for (const [key, value] of Object.entries(input ?? {})) {
+            if (value !== undefined && value !== null)
+                body[key] = value;
+        }
+        if (this.agentId !== undefined)
+            body.agent_id = this.agentId;
+        if (this.userId !== undefined)
+            body.user_id = this.userId;
+        const headers = { 'content-type': 'application/json' };
+        if (this.token)
+            headers.authorization = `Bearer ${this.token}`;
+        let response;
+        try {
+            response = await this.fetchImpl(this.url, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(body),
+                signal: AbortSignal.timeout(this.timeoutMs),
+            });
+        }
+        catch (err) {
+            throw new MemoryToolError(`mentedb unreachable at ${this.url}: ${err.message}`);
+        }
+        const text = await response.text();
+        if (!response.ok) {
+            throw new MemoryToolError(`mentedb ${response.status}: ${text}`, response.status);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            throw new MemoryToolError(`unexpected memory tool reply: ${text}`, response.status);
+        }
+        const reply = parsed;
+        if (!reply || typeof reply.content !== 'string') {
+            throw new MemoryToolError(`unexpected memory tool reply: ${text}`, response.status);
+        }
+        return { content: reply.content, is_error: Boolean(reply.is_error) };
+    }
+    /** Turn one memory `tool_use` block into its `tool_result` block. */
+    async handle(toolUse) {
+        const result = await this.execute((toolUse.input ?? {}));
+        const block = {
+            type: 'tool_result',
+            tool_use_id: toolUse.id ?? '',
+            content: result.content,
+        };
+        if (result.is_error)
+            block.is_error = true;
+        return block;
+    }
+    /**
+     * `tool_result` blocks for every memory call in an assistant turn. Pass
+     * `response.content`; other blocks are skipped. Send all results in one
+     * user message.
+     */
+    async results(content) {
+        const out = [];
+        for (const block of content) {
+            if (block.type === 'tool_use' && block.name === exports.MEMORY_TOOL_DEFINITION.name) {
+                out.push(await this.handle(block));
+            }
+        }
+        return out;
+    }
+}
+exports.MemoryTool = MemoryTool;
+/** Tool definition to pass in `tools` on a Messages API request. */
+MemoryTool.TOOL = exports.MEMORY_TOOL_DEFINITION;

package/npm/types.d.ts

@@ -31,6 +31,42 @@ export interface StoreOptions {
     embedding?: number[];
     agentId?: string;
     tags?: string[];
+    /** The session the memory is written in (its provenance). */
+    sessionId?: string;
+    /** chat, file, api, mcp, import, or another name. Defaults to api. */
+    source?: string;
+    /** A file path, URL or message id within the source. */
+    sourceRef?: string;
+}
+/**
+ * Where a memory came from, recorded when it was first written and never
+ * changed afterwards. See docs/PROVENANCE.md.
+ */
+export interface Provenance {
+    sessionId?: string | null;
+    source: string;
+    sourceRef?: string | null;
+    writtenBy: string;
+    /** Microseconds since the Unix epoch. */
+    writtenAt: number;
+    /** For a derived memory, the memories it was made from. */
+    derivedFrom: string[];
+}
+/** One stored memory, as `getMemory` returns it. */
+export interface Memory {
+    id: string;
+    content: string;
+    memoryType: string;
+    agentId: string;
+    tags: string[];
+    createdAt: number;
+    /** Absent for a memory written before provenance existed. */
+    provenance?: Provenance | null;
+}
+/** Narrow a search to memories by provenance. */
+export interface ProvenanceFilter {
+    sessionId?: string;
+    source?: string;
 }
 /** A single memory selected for the working-context window. */
 export interface ContextItem {
@@ -103,8 +139,20 @@ export interface ResidualHit {
     kind: 'content' | 'embedding';
 }
 /** Result of `MenteDB.erase`. Carries ids and hashes, never content. */
-export interface ErasureReceipt {
+export interface ErasureReceipt extends ErasureOutcome {
     requested: string;
+}
+/**
+ * Result of `MenteDB.eraseSession`: one erase over every memory written in
+ * the session and everything derived from them.
+ */
+export interface SessionErasureReceipt extends ErasureOutcome {
+    session_id: string;
+    /** The memories written in the session. */
+    requested: string[];
+}
+/** What every erase receipt carries. */
+export interface ErasureOutcome {
     erased: ErasedMemory[];
     ancestors_kept: string[];
     profiles_to_review: string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mentedb",
-  "version": "0.47.0",
+  "version": "0.48.0",
   "description": "The mind database for AI agents",
   "main": "npm/index.js",
   "types": "npm/index.d.ts",