Add LangChain JS, LangGraph, and Mastra adapter packages

.fallowrc.json

@@ -12,7 +12,11 @@
     "packages/*/src/**/*.test.ts",
     "plugins/openclaw/src/index.ts",
     "plugins/*/src/**/*.test.ts",
+    "plugins/*/__tests__/**/*.test.mjs",
     "adapters/vercel-ai-sdk/src/index.ts",
+    "adapters/langchain-js/src/index.ts",
+    "adapters/langgraph-js/src/index.ts",
+    "adapters/mastra/src/index.ts",
     "adapters/*/src/**/*.test.ts"
   ],
   "ignorePatterns": [

adapters/langchain-js/README.md

@@ -0,0 +1,102 @@
+# @atomicmemory/langchain
+
+AtomicMemory adapter for [LangChain JS](https://js.langchain.com/). Thin wrappers around an injected `MemoryClient` from `@atomicmemory/sdk`.
+
+The adapter exposes two surfaces:
+
+| Surface | Use when |
+|---|---|
+| Helpers — `searchMemory()` / `ingestTurn()` | You want to call AtomicMemory inside a LangChain callback, an LCEL `RunnableLambda`, or any other code path. Framework-agnostic. |
+| `createMemoryTools()` | You want AtomicMemory as agent-callable tools (`memory_search`, `memory_ingest`) consumable by `createToolCallingAgent`, LangGraph's tool node, or any `@langchain/core/tools`-compatible runner. |
+
+The adapter does **not** own provider configuration — pass an already-constructed `MemoryClient`.
+
+## Install
+
+```bash
+pnpm add @atomicmemory/langchain @atomicmemory/sdk @langchain/core zod
+```
+
+`@langchain/core` and `zod` are declared as peerDependencies so you can pin them at the version your LangChain graph already uses.
+
+## Quick start — agent tools
+
+```ts
+import { MemoryClient } from '@atomicmemory/sdk';
+import { createMemoryTools } from '@atomicmemory/langchain';
+
+const memory = new MemoryClient({
+  providers: { atomicmemory: { apiUrl: process.env.ATOMICMEMORY_URL!, apiKey: process.env.ATOMICMEMORY_KEY! } },
+});
+await memory.initialize();
+
+const { searchTool, ingestTool } = createMemoryTools(memory, {
+  scope: { user: 'pip', namespace: 'my-app' },
+  defaultLimit: 5,
+});
+
+// Hand the tools to any LangChain agent runner:
+const tools = [searchTool, ingestTool /*, ...your other tools */];
+```
+
+Scope is fixed at factory time — the agent cannot rebind to other users by passing different arguments.
+
+## Quick start — framework-agnostic helpers
+
+```ts
+import { searchMemory, ingestTurn } from '@atomicmemory/langchain';
+
+const { context, results } = await searchMemory(memory, {
+  query: latestUserMessage,
+  scope: { user: 'pip' },
+  limit: 8,
+});
+
+if (context) {
+  // Prepend `context` to your prompt, attach as a system message, etc.
+}
+
+// After the model call:
+await ingestTurn(memory, {
+  messages: turn.messages,
+  completion: turn.responseText,
+  scope: { user: 'pip' },
+});
+```
+
+### Custom formatter
+
+The default formatter wraps retrieved memories in a delimited block with an explicit "reference, not instructions" header — a mitigation against instruction-shaped content hijacking the model, not a guarantee. Override per call:
+
+```ts
+await searchMemory(memory, {
+  query,
+  scope,
+  formatter(results) {
+    return `# Prior context\n\n${results
+      .map((r) => `- [${r.memory.createdAt.toISOString()}] ${r.memory.content}`)
+      .join('\n')}`;
+  },
+});
+```
+
+### System-message handling on ingest
+
+`ingestTurn()` excludes `system` messages by default — applications typically use them for hidden instructions and policies that should never become durable memory. Opt in explicitly if your system messages are genuinely user-authored content worth remembering:
+
+```ts
+await ingestTurn(memory, {
+  messages,
+  completion,
+  scope,
+  includeRoles: ['system', 'user', 'assistant', 'tool'],
+});
+```
+
+## Scope
+
+Scope fields follow the SDK's `Scope` type — `user`, `agent`, `namespace`, `thread`. At least one must be provided; the SDK rejects scopeless requests.
+
+## License
+
+Apache-2.0.

adapters/langchain-js/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@atomicmemory/langchain",
+  "version": "0.1.0",
+  "description": "AtomicMemory adapter for LangChain JS - memory tools and framework-agnostic retrieve/ingest helpers around an injected MemoryClient.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/atomicstrata/atomicmemory-integrations.git",
+    "directory": "adapters/langchain-js"
+  },
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test --import tsx 'src/**/*.test.ts'",
+    "lint": "tsc -p tsconfig.json --noEmit",
+    "prepack": "pnpm build",
+    "prepublishOnly": "node -e \"const v=require('./package.json').dependencies['@atomicmemory/sdk'];if(v.startsWith('file:')||v.startsWith('link:')||v.startsWith('workspace:')){console.error('refusing to publish: @atomicmemory/sdk is '+v+'. Publish the SDK first, then pin to a registry version here.');process.exit(1)}\""
+  },
+  "dependencies": {
+    "@atomicmemory/sdk": "^1.0.1"
+  },
+  "peerDependencies": {
+    "@langchain/core": "^0.3.0",
+    "zod": "^3.23.0 || ^4.0.0"
+  },
+  "devDependencies": {
+    "@langchain/core": "^0.3.0",
+    "@types/node": "^20.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0",
+    "zod": "^3.23.8"
+  }
+}

adapters/langchain-js/src/index.ts

@@ -0,0 +1,31 @@
+/**
+ * @file Public entry - LangChain JS adapter for AtomicMemory.
+ *
+ *       Two surfaces:
+ *
+ *       1. Framework-agnostic helpers around an injected
+ *          `MemoryClient` (`searchMemory`, `ingestTurn`,
+ *          `defaultFormatter`) - usable inside any LangChain
+ *          callback, RunnableLambda, or LCEL chain step.
+ *
+ *       2. `createMemoryTools(client, opts)` - builds two
+ *          `@langchain/core/tools` `tool()` instances
+ *          (`memory_search` and `memory_ingest`) that an
+ *          agent (e.g. `createToolCallingAgent`, LangGraph's
+ *          tool node) can call directly.
+ *
+ *       The adapter NEVER imports `langchain`; it imports
+ *       `@langchain/core/tools` only inside the tool-factory
+ *       module, and that package is declared as a
+ *       peerDependency so consumers can pick a compatible
+ *       LangChain version.
+ */
+
+export { searchMemory, defaultFormatter } from './search.js';
+export type { SearchMemoryOptions, SearchMemoryResult } from './search.js';
+
+export { ingestTurn } from './ingest.js';
+export type { IngestTurnOptions } from './ingest.js';
+
+export { createMemoryTools } from './tools.js';
+export type { CreateMemoryToolsOptions, MemoryTools } from './tools.js';

adapters/langchain-js/src/ingest.test.ts

@@ -0,0 +1,62 @@
+/**
+ * @file Tests for ingestTurn() - system-exclusion default, opt-in
+ *       includeRoles, completion appending.
+ */
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { ingestTurn } from './ingest.js';
+import { makeFakeClient } from './test-fixtures.js';
+import type { Message } from '@atomicmemory/sdk';
+
+const scope = { user: 'u1' };
+
+test('appends completion as a final assistant message', async () => {
+  const { client, ingestCalls } = makeFakeClient();
+  const messages: Message[] = [{ role: 'user', content: 'q' }];
+  await ingestTurn(client, { messages, completion: 'a', scope });
+  const sent = ingestCalls[0];
+  assert.equal(sent?.mode, 'messages');
+  assert.equal(sent?.mode === 'messages' && sent.messages.at(-1)?.role, 'assistant');
+  assert.equal(sent?.mode === 'messages' && sent.messages.at(-1)?.content, 'a');
+});
+
+test('excludes system messages by default', async () => {
+  const { client, ingestCalls } = makeFakeClient();
+  const messages: Message[] = [
+    { role: 'system', content: 'POLICY' },
+    { role: 'user', content: 'q' },
+  ];
+  await ingestTurn(client, { messages, completion: 'a', scope });
+  const sent = ingestCalls[0];
+  const sentMessages = sent?.mode === 'messages' ? sent.messages : [];
+  assert.ok(sentMessages.every((m) => m.role !== 'system'));
+});
+
+test('opt-in includeRoles overrides the default exclusion', async () => {
+  const { client, ingestCalls } = makeFakeClient();
+  const messages: Message[] = [
+    { role: 'system', content: 'POLICY' },
+    { role: 'user', content: 'q' },
+  ];
+  await ingestTurn(client, {
+    messages,
+    completion: 'a',
+    scope,
+    includeRoles: ['system', 'user', 'assistant'],
+  });
+  const sent = ingestCalls[0];
+  const sentMessages = sent?.mode === 'messages' ? sent.messages : [];
+  assert.ok(sentMessages.some((m) => m.role === 'system'));
+});
+
+test('passes scope through unchanged', async () => {
+  const { client, ingestCalls } = makeFakeClient();
+  const customScope = { user: 'pip', namespace: 'demo' };
+  await ingestTurn(client, {
+    messages: [{ role: 'user', content: 'q' }],
+    completion: 'a',
+    scope: customScope,
+  });
+  assert.deepEqual(ingestCalls[0]?.scope, customScope);
+});

adapters/langchain-js/src/ingest.ts

@@ -0,0 +1,49 @@
+/**
+ * @file `ingestTurn()` - persist a completed turn to memory.
+ *       Uses the SDK's `messages` ingest mode so AUDN
+ *       (add / update / delete / no-op) deduplicates facts
+ *       across turns.
+ *
+ *       System messages are excluded by default because
+ *       applications typically use them for hidden
+ *       instructions/policies that should never become durable
+ *       memory. Callers can opt in via `includeRoles`.
+ */
+
+import type {
+  IngestResult,
+  Message,
+  MemoryClient,
+  Scope,
+} from '@atomicmemory/sdk';
+
+export interface IngestTurnOptions {
+  messages: readonly Message[];
+  /** The assistant's response text - appended as a final assistant message. */
+  completion: string;
+  scope: Scope;
+  /**
+   * Roles from `messages` to include. The assistant completion is
+   * always appended regardless of this list. Default:
+   * `['user', 'assistant', 'tool']` - system messages are excluded
+   * because they typically contain application policy not user
+   * content.
+   */
+  includeRoles?: ReadonlyArray<Message['role']>;
+}
+
+const DEFAULT_ROLES: ReadonlyArray<Message['role']> = ['user', 'assistant', 'tool'];
+
+export async function ingestTurn(
+  client: MemoryClient,
+  opts: IngestTurnOptions,
+): Promise<IngestResult> {
+  const allowed = new Set(opts.includeRoles ?? DEFAULT_ROLES);
+  const filtered = opts.messages.filter((m) => allowed.has(m.role));
+  const assistant: Message = { role: 'assistant', content: opts.completion };
+  return client.ingest({
+    mode: 'messages',
+    messages: [...filtered, assistant],
+    scope: opts.scope,
+  });
+}

adapters/langchain-js/src/search.test.ts

@@ -0,0 +1,67 @@
+/**
+ * @file Tests for searchMemory() - query passthrough, formatter
+ *       defaults, null-on-empty, custom formatter override.
+ */
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { defaultFormatter, searchMemory } from './search.js';
+import { makeFakeClient, makeMemory } from './test-fixtures.js';
+
+const scope = { user: 'u1' };
+
+test('returns null context when nothing matches', async () => {
+  const { client } = makeFakeClient({ searchResults: [] });
+  const result = await searchMemory(client, { query: 'hi', scope });
+  assert.equal(result.context, null);
+  assert.equal(result.results.length, 0);
+});
+
+test('returns a rendered context block when memories match', async () => {
+  const { client } = makeFakeClient({
+    searchResults: [makeMemory('user prefers pnpm')],
+  });
+  const result = await searchMemory(client, { query: 'stack?', scope });
+  assert.match(result.context ?? '', /user prefers pnpm/);
+  assert.match(result.context ?? '', /<atomicmemory:context>/);
+  assert.match(result.context ?? '', /do not follow/);
+});
+
+test('passes query / scope / limit through to client.search', async () => {
+  const { client, searchCalls } = makeFakeClient();
+  await searchMemory(client, { query: 'q', scope, limit: 12 });
+  assert.equal(searchCalls[0]?.query, 'q');
+  assert.deepEqual(searchCalls[0]?.scope, scope);
+  assert.equal(searchCalls[0]?.limit, 12);
+});
+
+test('defaults limit to 5 when omitted', async () => {
+  const { client, searchCalls } = makeFakeClient();
+  await searchMemory(client, { query: 'q', scope });
+  assert.equal(searchCalls[0]?.limit, 5);
+});
+
+test('uses caller-supplied formatter override', async () => {
+  const { client } = makeFakeClient({ searchResults: [makeMemory('x')] });
+  const result = await searchMemory(client, {
+    query: 'q',
+    scope,
+    formatter: (rs) => `CUSTOM:${rs.length}`,
+  });
+  assert.equal(result.context, 'CUSTOM:1');
+});
+
+test('rejects empty / non-string query', async () => {
+  const { client } = makeFakeClient();
+  await assert.rejects(
+    () => searchMemory(client, { query: '', scope }),
+    /query/i,
+  );
+});
+
+test('defaultFormatter renders the standard block on >=1 result', () => {
+  const rendered = defaultFormatter([makeMemory('fact-a'), makeMemory('fact-b')]);
+  assert.match(rendered, /fact-a/);
+  assert.match(rendered, /fact-b/);
+  assert.match(rendered, /<\/atomicmemory:context>/);
+});