memtrails 0.5.2 → 0.5.3

package/CHANGELOG.md

@@ -5,6 +5,15 @@ versions follow [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.5.3] — 2026-11-05
+
+- LangChain and LlamaIndex retrievers: `memtrails/langchain` (with `@langchain/core` beside it, an optional peer), and
+  in Python `memtrails.integrations.langchain` and `memtrails.integrations.llama_index` (`pip install
+  memtrails[langchain]` / `[llama-index]`). Each found item becomes the framework's document with the same id, text and
+  flat metadata in both languages (`conformance/fixtures/retriever.json`). No TypeScript LlamaIndex adapter: its
+  packages are no longer maintained.
+  The Rust version is released at the same version, unchanged (LangChain and LlamaIndex are Python and JavaScript).
+
 ## [0.5.2] — 2026-11-05
 
 - Examples in Python and Rust, the same four as in TypeScript (a quick start, importing sources, the agent tools,

package/README.md

@@ -100,6 +100,22 @@ The memory lives in `~/.memtrails` (`--home` or `MEMTRAILS_HOME` for another). T
 call and closes it after five minutes without one (`--idle`), so `add` can run in between; `--read-only` leaves out
 `memory_save`. From code: `serveMcp({ open: () => openMemory({ home }), version })`.
 
+## LangChain and LlamaIndex
+
+A memory is a LangChain retriever (install `@langchain/core` beside memtrails):
+
+```ts
+import { MemtrailsRetriever } from 'memtrails/langchain';
+const docs = await new MemtrailsRetriever({ memory, search: { limit: 8 } }).invoke('why did renewal stop?');
+```
+
+Each document is a found item: its summary (and the passage that matched) as the text, its id, and flat metadata
+(`id`, `kind`, `title`, `date`, `ts`, `score`, and when it has them `eventAt`/`startAt`/`endAt`, `recordId`, `source`,
+`author`, `url`); `memory.open(id)` gives all of it. `search` takes every search option but the query (`collections`,
+`kinds`, `limit`, `from`, `to`; `limit` counts dated observations and other memories each). In Python, LangChain and
+LlamaIndex both: `memtrails.integrations.langchain` and `memtrails.integrations.llama_index`. (LlamaIndex's TypeScript
+packages are no longer maintained, so there is no TypeScript LlamaIndex adapter.)
+
 ## Adding data
 
 A **record** is anything with text. Only `id` and `text` are required.

package/dist/integrations/document.d.ts

@@ -0,0 +1,14 @@
+/**
+ * A found item as a framework's document (a LangChain `Document`; in Python also a LlamaIndex `TextNode`): its id,
+ * the text a model reads, and flat metadata a vector store or a prompt can carry. `memory.open(id)` gives the whole item.
+ */
+import type { RecalledItem } from '../core/recall.js';
+export interface RetrievedDocument {
+    id: string;
+    /** The item's summary, and the passage that matched when that was not its start. */
+    text: string;
+    /** id, kind, title, date (YYYY-MM-DD of `ts`), ts, score; for an observation eventAt, startAt, endAt; for a record you
+     *  added recordId, source, author, url. Only the ones it has. */
+    metadata: Record<string, string | number>;
+}
+export declare function retrievedDocument(h: RecalledItem): RetrievedDocument;

package/dist/integrations/document.js

@@ -0,0 +1,19 @@
+export function retrievedDocument(h) {
+    const m = {
+        id: h.id,
+        kind: h.kind,
+        title: h.title,
+        date: h.ts > 0 ? new Date(h.ts).toISOString().slice(0, 10) : undefined,
+        ts: h.ts,
+        score: h.score,
+        eventAt: h.eventAt,
+        startAt: h.startAt,
+        endAt: h.endAt,
+        recordId: h.record?.id,
+        source: h.record?.source,
+        author: h.record?.author,
+        url: h.record?.url,
+    };
+    const metadata = Object.fromEntries(Object.entries(m).filter((e) => e[1] !== undefined && e[1] !== ''));
+    return { id: h.id, text: h.match ? `${h.summary} … ${h.match}` : h.summary, metadata };
+}

package/dist/langchain.d.ts

@@ -0,0 +1,27 @@
+/**
+ * A memory as a LangChain retriever (`@langchain/core`, installed beside memtrails):
+ *
+ *   import { MemtrailsRetriever } from 'memtrails/langchain';
+ *   const retriever = new MemtrailsRetriever({ memory, search: { limit: 8 } });
+ *   const docs = await retriever.invoke('why did the certificate stop renewing?');
+ *
+ * Each Document is a found item: its summary (and the passage that matched) as `pageContent`, its id, and flat metadata
+ * (integrations/document.ts). `search` is every search option but the query: collections, kinds, limit, from, to.
+ */
+import { Document } from '@langchain/core/documents';
+import { BaseRetriever, type BaseRetrieverInput } from '@langchain/core/retrievers';
+import type { RecalledItem, SearchQuery } from './core/recall.js';
+export interface MemtrailsRetrieverInput extends BaseRetrieverInput {
+    /** An open memory (openMemory), or anything that searches like one. */
+    memory: {
+        search(q: SearchQuery): Promise<RecalledItem[]>;
+    };
+    search?: Omit<SearchQuery, 'query'>;
+}
+export declare class MemtrailsRetriever extends BaseRetriever {
+    lc_namespace: string[];
+    private readonly memory;
+    private readonly search;
+    constructor(fields: MemtrailsRetrieverInput);
+    _getRelevantDocuments(query: string): Promise<Document[]>;
+}

package/dist/langchain.js

@@ -0,0 +1,30 @@
+/**
+ * A memory as a LangChain retriever (`@langchain/core`, installed beside memtrails):
+ *
+ *   import { MemtrailsRetriever } from 'memtrails/langchain';
+ *   const retriever = new MemtrailsRetriever({ memory, search: { limit: 8 } });
+ *   const docs = await retriever.invoke('why did the certificate stop renewing?');
+ *
+ * Each Document is a found item: its summary (and the passage that matched) as `pageContent`, its id, and flat metadata
+ * (integrations/document.ts). `search` is every search option but the query: collections, kinds, limit, from, to.
+ */
+import { Document } from '@langchain/core/documents';
+import { BaseRetriever } from '@langchain/core/retrievers';
+import { retrievedDocument } from './integrations/document.js';
+export class MemtrailsRetriever extends BaseRetriever {
+    lc_namespace = ['memtrails', 'retrievers'];
+    memory;
+    search;
+    constructor(fields) {
+        super(fields);
+        this.memory = fields.memory;
+        this.search = fields.search ?? {};
+    }
+    async _getRelevantDocuments(query) {
+        const hits = await this.memory.search({ ...this.search, query });
+        return hits.map((h) => {
+            const d = retrievedDocument(h);
+            return new Document({ id: d.id, pageContent: d.text, metadata: d.metadata });
+        });
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memtrails",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "description": "Retrieval and exploration for any text — e-mail, chat, notes, documents, news, commits, conversations. Searchable at once, on your own machine, in any language; optional consolidation into typed knowledge with a language model.",
   "keywords": [
     "retrieval",
@@ -41,6 +41,10 @@
       "types": "./dist/importers/index.d.ts",
       "import": "./dist/importers/index.js"
     },
+    "./langchain": {
+      "types": "./dist/langchain.d.ts",
+      "import": "./dist/langchain.js"
+    },
     "./package.json": "./package.json"
   },
   "bin": {
@@ -71,6 +75,7 @@
     "onnxruntime-node": "1.23.2"
   },
   "devDependencies": {
+    "@langchain/core": "1.3.4",
     "@modelcontextprotocol/sdk": "1.32.2",
     "@types/node": "^22.10.0",
     "esbuild": "^0.25.12",
@@ -80,5 +85,13 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "peerDependencies": {
+    "@langchain/core": ">=1.0.0 <2"
+  },
+  "peerDependenciesMeta": {
+    "@langchain/core": {
+      "optional": true
+    }
   }
 }