memtrails 0.5.2 → 0.5.4

package/CHANGELOG.md

@@ -5,6 +5,25 @@ versions follow [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.5.4] — 2026-11-05
+
+- Windows (x64), in all three languages, tested on every change (the tests, and a real memory searched with the real
+  model and Qdrant). Fixed on the way: TypeScript rewrote a log over a file still open; Python checked a
+  process with `os.kill(pid, 0)`, which on Windows sends Ctrl+C to its console group, wrote `\r\n` where the files say
+  `\n` (records then read back as missing), removed lock files while they were open, took a time-zone offset 2³³
+  seconds off for some years, and printed in the console's code page; Rust took every process for alive, never stopped
+  its Qdrant at exit, and unpacked the Windows ONNX Runtime as gzip; and in all three, a lock being let go by another
+  process failed the one taking it. A memory whose path is too long for Qdrant's files on Windows is now said to be so.
+
+## [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

@@ -58,10 +58,17 @@ More to run in [`examples/`](https://github.com/cmaftuleac/memtrails/blob/main/e
 npm install memtrails
 ```
 
-Node.js 22 or newer, on macOS or Linux (x64 or arm64). Windows has the pieces it needs but is not tested yet. The first `openMemory` downloads the embedding model
+Node.js 22 or newer, on macOS or Linux (x64 or arm64) or Windows (x64). The first `openMemory` downloads the embedding model
 (218 MB, from Hugging Face) and the Qdrant binary (~30 MB, from Qdrant's GitHub release) into `~/.cache/memtrails`,
 each checked against a pinned SHA-256. Set `MEMTRAILS_CACHE` to put them elsewhere.
 
+On Windows, keep a memory's path under 90 characters: Qdrant's files sit up to about 170 characters deeper, and
+Windows stops a path at 260 (memtrails says so when one is longer).
+
+On Linux x64, `ONNXRUNTIME_NODE_INSTALL=skip npm install memtrails` skips the CUDA libraries ONNX Runtime's installer
+downloads otherwise (about 350 MB; memtrails runs on the CPU and never uses them; see [SECURITY.md](SECURITY.md)). In
+an MCP client's configuration the same goes in `"env": { "ONNXRUNTIME_NODE_INSTALL": "skip" }`.
+
 ### Python and Rust
 
 The same library, written natively in each language, fully async, with the same results and the same files: a memory
@@ -100,6 +107,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/core/qdrant-binary.d.ts

@@ -56,6 +56,11 @@ export declare const LOCK_STALE_MS = 120000;
  * rests on the lock for correctness (every file is verified in a private temp and renamed into place); it keeps two
  * runs from fetching the same hundreds of MB, and from swapping folders under each other.
  */
+/** How long "access denied" on making a lock is taken for one being removed (Windows) before it is an error. */
+export declare const DELETE_PENDING_MS = 2000;
+/** Windows answers "access denied", not "exists" or "not found", for a file another process is removing at that moment:
+ *  a lock being let go. A moment later it is gone. Elsewhere that answer is a real refusal. */
+export declare function beingRemoved(err: unknown): boolean;
 export declare function withLock<T>(path: string, f: () => Promise<T>, o?: {
     signal?: AbortSignal;
     staleMs?: number;

package/dist/core/qdrant-binary.js

@@ -169,11 +169,20 @@ function lockStale(lock, staleMs) {
  * rests on the lock for correctness (every file is verified in a private temp and renamed into place); it keeps two
  * runs from fetching the same hundreds of MB, and from swapping folders under each other.
  */
+/** How long "access denied" on making a lock is taken for one being removed (Windows) before it is an error. */
+export const DELETE_PENDING_MS = 2000;
+/** Windows answers "access denied", not "exists" or "not found", for a file another process is removing at that moment:
+ *  a lock being let go. A moment later it is gone. Elsewhere that answer is a real refusal. */
+export function beingRemoved(err) {
+    const code = err.code;
+    return process.platform === 'win32' && (code === 'EPERM' || code === 'EACCES');
+}
 export async function withLock(path, f, o = {}) {
     const lock = `${path}.lock`;
     const staleMs = o.staleMs ?? LOCK_STALE_MS;
     const mine = `${process.pid} ${hostname()} ${randomBytes(8).toString('hex')}`;
     mkdirSync(dirname(lock), { recursive: true });
+    let denied = null;
     for (;;) {
         try {
             const fd = openSync(lock, 'wx', 0o600);
@@ -182,8 +191,13 @@ export async function withLock(path, f, o = {}) {
             break;
         }
         catch (err) {
+            if (beingRemoved(err) && Date.now() - (denied ??= Date.now()) < DELETE_PENDING_MS) {
+                await new Promise((ok) => setTimeout(ok, o.pollMs ?? 250));
+                continue;
+            }
             if (err.code !== 'EEXIST')
                 throw err;
+            denied = null;
         }
         if (lockStale(lock, staleMs)) {
             rmSync(lock, { force: true });

package/dist/core/store.js

@@ -166,7 +166,7 @@ export class JsonlLog {
         const order = [...this.live.entries()].sort((a, b) => a[1].at - b[1].at);
         const tmp = `${this.path}.compact`;
         const next = new Map();
-        const src = openSync(this.path, 'r');
+        let src = openSync(this.path, 'r');
         let out = null;
         try {
             out = openSync(tmp, 'w', 0o600);
@@ -195,6 +195,9 @@ export class JsonlLog {
             fsyncSync(out);
             closeSync(out);
             out = null;
+            // Closed before the rename: Windows does not replace a file that is open.
+            closeSync(src);
+            src = null;
             renameSync(tmp, this.path);
             this.live.clear();
             for (const [uid, s] of next)
@@ -209,7 +212,8 @@ export class JsonlLog {
             throw e;
         }
         finally {
-            closeSync(src);
+            if (src !== null)
+                closeSync(src);
         }
     }
 }

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/dist/memory.js

@@ -21,7 +21,7 @@ import { remoteEmbedder, resolveEmbedRoute } from './core/embedder.js';
 import { memoryGather } from './core/gather.js';
 import { loadLocalEmbedder } from './core/local-embedder.js';
 import { ensureModel } from './core/model.js';
-import { ensureQdrant } from './core/qdrant-binary.js';
+import { beingRemoved, DELETE_PENDING_MS, ensureQdrant } from './core/qdrant-binary.js';
 import { COLLECTION, INDEX_LAYOUT, QdrantClient } from './core/qdrant-client.js';
 import { alive, bootTime, QdrantProcess, sameBoot } from './core/qdrant-process.js';
 import { memoryExplore, memoryOpen, memorySearch } from './core/recall.js';
@@ -76,14 +76,21 @@ function lockHolder(path) {
  *  ran before a reboot (its pid may be another's now), is taken over. Returns its release. */
 function lockHome(dir) {
     const path = join(dir, LOCK_FILE);
+    let denied = null;
     for (let attempt = 0;; attempt++) {
         let fd;
         try {
             fd = openSync(path, 'wx', 0o600);
         }
         catch (err) {
+            if (beingRemoved(err) && Date.now() - (denied ??= Date.now()) < DELETE_PENDING_MS) {
+                Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10); // a moment, then again
+                attempt--;
+                continue;
+            }
             if (err.code !== 'EEXIST')
                 throw err;
+            denied = null;
             const { text, pid } = lockHolder(path);
             if (pid !== null || attempt > 0) {
                 throw new Error(`memory ${dir} is open${pid ? ` in process ${pid}` : ''}: close it there first (if no process has it, delete ${path})`);
@@ -197,7 +204,18 @@ export async function openMemory(o) {
         throw err;
     }
 }
+/** Windows stops at 260 characters a path, and Qdrant's files sit up to about 170 below a memory's own folder. */
+const WINDOWS_HOME_MAX = 90;
+/** Said before Qdrant fails on it with no more than "the system cannot find the path specified". */
+function windowsHomeTooLong(dir, o, log) {
+    if (process.platform !== 'win32' || (o.qdrant && 'url' in o.qdrant) || dir.length <= WINDOWS_HOME_MAX)
+        return;
+    log(`[memtrails] ${dir} is ${dir.length} characters long: on Windows, Qdrant's files sit up to about 170 characters `
+        + `deeper and a path stops at 260, so the index may fail ("the system cannot find the path specified"); keep a `
+        + `memory's path under ${WINDOWS_HOME_MAX} characters`);
+}
 async function openIn(dir, o, log, started, release) {
+    windowsHomeTooLong(dir, o, log);
     // Embedding: here, or on a server — the options' own, else the one the environment names.
     const e = o.embedding ?? {};
     const server = e.server ?? (e.modelDir ? null : resolveEmbedRoute());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memtrails",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "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
+    }
   }
 }