Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
408 changes: 169 additions & 239 deletions docs/design/external-context-mem0-extension.md

Large diffs are not rendered by default.

100 changes: 75 additions & 25 deletions integrations/external-context-mem0/README.md
Original file line number Diff line number Diff line change
@@ -1,37 +1,87 @@
# Mem0 External Context Extension

This package is the retrieval-only Extension defined by the
[Configurable Mem0 Provider Extension](../../docs/design/external-context-mem0-extension.md)
proposal. It implements the External Context MCP Profile v1 server, validates
administrator-owned instance configuration and closed dialect definitions, and
contains a bounded HTTP request engine.

This PR1 package intentionally ships no live provider preset. Its built-in
preset registry is empty, so the process fails closed with an unknown-preset
configuration error. Verified Mem0 Platform and PolarDB presets are staged for
PR2. Do not install this intermediate package as a usable provider Extension.

## Configuration contract

`QWEN_EXTERNAL_CONTEXT_MEM0_CONFIG` must contain the absolute path of an
instance JSON file conforming to
[`schemas/instance-config.schema.json`](./schemas/instance-config.schema.json).
The instance selects one immutable built-in preset and binds its endpoint,
credential environment-variable name, scope, and timeout. Credential values
never belong in the instance file.

Preset authors must conform to
[`schemas/dialect.schema.json`](./schemas/dialect.schema.json). The schema and
semantic validator intentionally support only the bounded request and response
This package provides a retrieval-only External Context MCP Profile v1 server
for administrator-configured Mem0-compatible HTTP services. It validates a
closed dialect grammar and uses a bounded HTTP request engine; it does not ship
provider presets or provider-specific configuration.

## Configuration

Set `QWEN_EXTERNAL_CONTEXT_MEM0_CONFIG` in the Extension process environment to
the absolute path of an administrator-owned instance JSON file. The instance
file must conform to
[`schemas/instance-config.schema.json`](./schemas/instance-config.schema.json)
and reference a separate dialect JSON file by absolute `dialectPath`:

```json
{
"schemaVersion": 2,
"dialectPath": "/etc/qwen/external-context/memory.dialect.json",
"endpoint": {
"origin": "https://memory.example.com",
"basePath": "",
"allowInsecureHttp": false
},
"credentialEnv": "MEMORY_API_KEY",
"scope": {
"userId": "repository-memory"
},
"timeoutMs": 5000
}
```

The dialect file must conform to
[`schemas/dialect.schema.json`](./schemas/dialect.schema.json). This synthetic
example describes one supported shape without identifying a provider:

```json
{
"dialectVersion": 1,
"id": "organization-memory-v1",
"auth": "authorization-bearer",
"search": {
"method": "POST",
"path": "/memories/search",
"queryLocation": "json",
"userIdLocation": "json.filters",
"agentIdLocation": "omit",
"appIdLocation": "omit",
"limitField": "limit"
},
"response": {
"collection": "results",
"idField": "id",
"contentField": "memory",
"titleField": "omit",
"uriField": "omit",
"scoreField": "score",
"updatedAtField": "omit"
}
}
```

The administrator controls both files and the process environment. Production
deployments should keep them outside ordinary workspaces and supply the
instance path through a system environment, controlled launcher, or pinned MCP
configuration. `dialectPath` is never resolved relative to the instance file,
expanded from environment variables, or loaded from a URL.

The credential value must exist only in the environment variable named by
`credentialEnv`; neither JSON file may contain it. Both files are limited to
64 KiB and are read once when the Extension starts. Restart the Extension after
changing either file.

The schema intentionally supports only the bounded request and response
grammar recorded in the design. Protocols that require arbitrary templates,
headers, JSONPath, redirects, or executable transformations must use a separate
MCP Extension.
headers, JSONPath, redirects, executable transformations, or write operations
must use a separate MCP Extension.

## Development

```bash
npm run test --workspace=@qwen-code/external-context-mem0
npm run typecheck --workspace=@qwen-code/external-context-mem0
npm run lint --workspace=@qwen-code/external-context-mem0
npm run build --workspace=@qwen-code/external-context-mem0
```

Expand Down
Original file line number Diff line number Diff line change
@@ -1,25 +1,23 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Mem0 External Context instance configuration v1",
"title": "Mem0 External Context instance configuration v2",
"type": "object",
"additionalProperties": false,
"required": [
"schemaVersion",
"preset",
"dialectPath",
"endpoint",
"credentialEnv",
"scope",
"timeoutMs"
],
"properties": {
"schemaVersion": {
"const": 1
"const": 2
},
"preset": {
"dialectPath": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"pattern": "^[a-z0-9]+(?:[a-z0-9.-]*[a-z0-9])?$"
"minLength": 1
},
"endpoint": {
"type": "object",
Expand Down
54 changes: 31 additions & 23 deletions integrations/external-context-mem0/src/config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -13,18 +13,17 @@ import {
} from './schemas.js';
import type {
DialectV1,
InstanceConfigV1,
InstanceConfigV2,
RuntimeConfiguration,
ScopeLocation,
} from './types.js';

const CONFIG_ENV = 'QWEN_EXTERNAL_CONTEXT_MEM0_CONFIG';
const MAX_CONFIG_BYTES = 64 * 1024;

export async function loadRuntimeConfiguration(options: {
presets: ReadonlyMap<string, unknown>;
env?: NodeJS.ProcessEnv;
}): Promise<RuntimeConfiguration> {
export async function loadRuntimeConfiguration(
options: { env?: NodeJS.ProcessEnv } = {},
): Promise<RuntimeConfiguration> {
const env = options.env ?? process.env;
const configPath = readRequiredEnvironment(env, CONFIG_ENV);
if (!isAbsolute(configPath)) {
Expand All @@ -33,15 +32,17 @@ export async function loadRuntimeConfiguration(options: {
);
}

const instance = parseInstanceConfig(await readConfigFile(configPath));
const preset = options.presets.get(instance.preset);
if (preset === undefined) {
throw new ConfigurationError('Mem0 extension preset is unknown.');
}
const dialect = parseDialect(preset);
if (dialect.id !== instance.preset) {
throw new ConfigurationError('Mem0 extension preset is invalid.');
const instance = parseInstanceConfig(
await readConfigFile(configPath, 'instance'),
);
if (!isAbsolute(instance.dialectPath)) {
throw new ConfigurationError(
'Mem0 extension dialect path must be absolute.',
);
}
const dialect = parseDialect(
await readConfigFile(instance.dialectPath, 'dialect'),
);

validateInstance(instance, dialect);
return {
Expand All @@ -51,7 +52,10 @@ export async function loadRuntimeConfiguration(options: {
};
}

async function readConfigFile(path: string): Promise<unknown> {
async function readConfigFile(
path: string,
kind: 'instance' | 'dialect',
): Promise<unknown> {
let source: Buffer;
let file: FileHandle | undefined;
try {
Expand All @@ -71,23 +75,27 @@ async function readConfigFile(path: string): Promise<unknown> {
source = source.subarray(0, offset);
} catch {
throw new ConfigurationError(
'Mem0 extension configuration is unavailable.',
`Mem0 extension ${kind} configuration is unavailable.`,
);
} finally {
await file?.close().catch(() => undefined);
}
if (source.byteLength > MAX_CONFIG_BYTES) {
throw new ConfigurationError('Mem0 extension configuration is invalid.');
throw new ConfigurationError(
`Mem0 extension ${kind} configuration is invalid.`,
);
}
try {
return JSON.parse(source.toString('utf8')) as unknown;
} catch {
throw new ConfigurationError('Mem0 extension configuration is invalid.');
throw new ConfigurationError(
`Mem0 extension ${kind} configuration is invalid.`,
);
}
}

function validateInstance(
instance: InstanceConfigV1,
instance: InstanceConfigV2,
dialect: DialectV1,
): void {
validateEndpoint(instance);
Expand All @@ -97,7 +105,7 @@ function validateInstance(
validateScope(instance, dialect);
}

function validateEndpoint(instance: InstanceConfigV1): void {
function validateEndpoint(instance: InstanceConfigV2): void {
let origin: URL;
try {
origin = new URL(instance.endpoint.origin);
Expand Down Expand Up @@ -157,11 +165,11 @@ function validateDialectSemantics(dialect: DialectV1): void {
dialect.search.appIdLocation,
];
if (locations.some((location) => location.startsWith('json'))) {
throw new ConfigurationError('Mem0 extension preset is invalid.');
throw new ConfigurationError('Mem0 extension dialect is invalid.');
}
}

function validateScope(instance: InstanceConfigV1, dialect: DialectV1): void {
function validateScope(instance: InstanceConfigV2, dialect: DialectV1): void {
requireScopeValue(instance.scope.userId, dialect.search.userIdLocation);
requireScopeValue(instance.scope.agentId, dialect.search.agentIdLocation);
requireScopeValue(instance.scope.appId, dialect.search.appIdLocation);
Expand All @@ -180,14 +188,14 @@ function readRequiredEnvironment(env: NodeJS.ProcessEnv, name: string): string {
const trimmed = value?.trim();
if (!value || !trimmed || trimmed === '${' + name + '}') {
throw new ConfigurationError(
'Mem0 extension configuration is unavailable.',
'Mem0 extension instance configuration is unavailable.',
);
}
return value;
}

export function buildSearchUrl(
instance: InstanceConfigV1,
instance: InstanceConfigV2,
dialect: DialectV1,
): URL {
const url = new URL(instance.endpoint.origin);
Expand Down
1 change: 1 addition & 0 deletions integrations/external-context-mem0/src/main.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,7 @@ describe('Mem0 extension startup', () => {

await import('./main.js');

expect(loadRuntimeConfiguration).toHaveBeenCalledWith();
expect(createRequestEngine).toHaveBeenCalledWith(runtime);
expect(createMem0McpServer).toHaveBeenCalledWith({
instance: runtime.instance,
Expand Down
3 changes: 1 addition & 2 deletions integrations/external-context-mem0/src/main.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,12 +7,11 @@
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { loadRuntimeConfiguration } from './config.js';
import { createMem0McpServer } from './mcp.js';
import { builtInPresets } from './presets.js';
import { createRequestEngine } from './request-engine.js';
import { ConfigurationError } from './schemas.js';

try {
const runtime = await loadRuntimeConfiguration({ presets: builtInPresets });
const runtime = await loadRuntimeConfiguration();
const server = createMem0McpServer({
instance: runtime.instance,
search: createRequestEngine(runtime),
Expand Down
12 changes: 9 additions & 3 deletions integrations/external-context-mem0/src/manifest.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,6 @@

import { readFile } from 'node:fs/promises';
import { describe, expect, it } from 'vitest';
import { builtInPresets } from './presets.js';

describe('Mem0 Extension package', () => {
it('is self-contained and exposes only context_search', async () => {
Expand All @@ -31,8 +30,15 @@ describe('Mem0 Extension package', () => {
expect(packageJson.dependencies).toBeUndefined();
});

it('ships no live provider preset in PR1', () => {
expect([...builtInPresets]).toEqual([]);
it('ships only the runtime, schemas, manifest, and documentation', async () => {
const packageJson = await readJson('../package.json');

expect(packageJson.files).toEqual([
'dist/main.js',
'schemas',
'qwen-extension.json',
'README.md',
]);
});
});

Expand Down
4 changes: 2 additions & 2 deletions integrations/external-context-mem0/src/mcp.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -214,8 +214,8 @@ async function connect(
InMemoryTransport.createLinkedPair();
const server = createMem0McpServer({
instance: parseInstanceConfig({
schemaVersion: 1,
preset: 'synthetic-v1',
schemaVersion: 2,
dialectPath: '/administrator/synthetic-v1.dialect.json',
endpoint: { origin: 'https://memory.example.com' },
credentialEnv: 'SYNTHETIC_MEMORY_TOKEN',
scope: {},
Expand Down
4 changes: 2 additions & 2 deletions integrations/external-context-mem0/src/mcp.ts
Original file line number Diff line number Diff line change
Expand Up @@ -11,10 +11,10 @@ import {
outputSchema,
renderResult,
} from './profile.js';
import type { InstanceConfigV1, SearchProvider } from './types.js';
import type { InstanceConfigV2, SearchProvider } from './types.js';

export function createMem0McpServer(runtime: {
instance: InstanceConfigV1;
instance: InstanceConfigV2;
search: SearchProvider;
}): McpServer {
const server = new McpServer({
Expand Down
7 changes: 0 additions & 7 deletions integrations/external-context-mem0/src/presets.ts

This file was deleted.

4 changes: 2 additions & 2 deletions integrations/external-context-mem0/src/request-engine.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ import { parseDialect, parseInstanceConfig } from './schemas.js';
import type {
DialectV1,
ExternalContextItem,
InstanceConfigV1,
InstanceConfigV2,
RuntimeConfiguration,
} from './types.js';

Expand Down Expand Up @@ -243,7 +243,7 @@ describe('bounded Mem0 request engine', () => {
});

interface SyntheticFixture {
instance: InstanceConfigV1;
instance: InstanceConfigV2;
dialect: DialectV1;
credential: string;
query: string;
Expand Down
Loading
Loading