@trylucy/agent-memory 0.0.0-stage → 0.1.2

package/src/mcp/config.mjs

@@ -0,0 +1,60 @@
+import { isAbsolute } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { createLucyHttpTransport } from '../client/http-transport.mjs';
+import { McpLifecycleError, runLifecycleStage } from './lifecycle.mjs';
+
+const PUBLIC_PERMISSIONS = new Set(['memory:read', 'memory:propose']);
+const configurationError = () => new McpLifecycleError('CONFIGURATION_ERROR');
+
+export function loadLucyMemoryMcpConfig(environment = process.env) {
+  const token = environment.LUCY_MEMORY_TOKEN;
+  if (typeof token !== 'string' || token.length === 0 || /[\r\n\0]/.test(token)) throw configurationError();
+  const permissions = String(environment.LUCY_MEMORY_PERMISSIONS ?? '')
+    .split(',')
+    .map((value) => value.trim())
+    .filter(Boolean);
+  if (permissions.length === 0 || new Set(permissions).size !== permissions.length
+      || permissions.some((permission) => !PUBLIC_PERMISSIONS.has(permission))) throw configurationError();
+  const timeoutMs = Number(environment.LUCY_MEMORY_TIMEOUT_MS ?? 10_000);
+  if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 300_000) throw configurationError();
+  const insecureLoopbackSetting = environment.LUCY_MEMORY_ALLOW_INSECURE_LOOPBACK;
+  if (insecureLoopbackSetting !== undefined && insecureLoopbackSetting !== 'true' && insecureLoopbackSetting !== 'false') throw configurationError();
+  const allowInsecureLoopback = insecureLoopbackSetting === 'true';
+  const baseUrl = environment.LUCY_MEMORY_BASE_URL;
+  const transportModule = environment.LUCY_MEMORY_TRANSPORT_MODULE;
+  const hasBase = typeof baseUrl === 'string' && baseUrl.length > 0;
+  const hasModule = typeof transportModule === 'string' && transportModule.length > 0;
+  if (hasBase === hasModule) throw configurationError();
+  if (hasBase && /[\r\n\0]/.test(baseUrl)) throw configurationError();
+  if (hasModule && (/[\r\n\0]/.test(transportModule) || (!transportModule.startsWith('file:') && !isAbsolute(transportModule)))) {
+    throw configurationError();
+  }
+  return Object.freeze({
+    token,
+    permissions: Object.freeze(permissions),
+    timeoutMs,
+    allowInsecureLoopback,
+    ...(hasBase ? { baseUrl } : { transportModule }),
+  });
+}
+
+export async function loadAgentMemoryTransport(moduleSpecifier) {
+  return runLifecycleStage('TRANSPORT_LOAD_ERROR', async () => {
+    const url = moduleSpecifier.startsWith('file:') ? new URL(moduleSpecifier) : pathToFileURL(moduleSpecifier);
+    if (url.protocol !== 'file:') throw new Error('unsupported protocol');
+    const loaded = await import(url.href);
+    const factory = loaded.createTransport ?? loaded.default;
+    if (typeof factory !== 'function') throw new Error('missing transport factory');
+    const transport = await factory();
+    if (typeof transport !== 'function') throw new Error('invalid transport factory result');
+    return transport;
+  });
+}
+
+export async function resolveLucyMemoryTransport(config) {
+  if (config.baseUrl) return createLucyHttpTransport({
+    baseUrl: config.baseUrl,
+    allowInsecureLoopback: config.allowInsecureLoopback,
+  });
+  return loadAgentMemoryTransport(config.transportModule);
+}

package/src/mcp/index.d.ts

@@ -0,0 +1,27 @@
+import type { Server } from '@modelcontextprotocol/server';
+import type { AgentMemoryClient } from '../client/index.js';
+
+export type LucyMemoryToolName = 'memory_recall' | 'memory_propose' | 'memory_proposal_status';
+export interface McpSafeError {
+  code: string;
+  message: string;
+  retryable: boolean;
+  status: number | null;
+  request_id?: `req_${string}`;
+}
+export interface LucyMemoryToolDefinition {
+  readonly name: LucyMemoryToolName;
+  readonly description: string;
+  readonly annotations: Readonly<Record<string, boolean>>;
+  readonly inputSchema: Readonly<Record<string, unknown>>;
+  readonly outputSchema: Readonly<Record<string, unknown>>;
+}
+export interface LucyMemoryMcpServerOptions {
+  client: AgentMemoryClient;
+  name?: string;
+  version?: string;
+}
+export const LUCY_MEMORY_TOOL_NAMES: readonly LucyMemoryToolName[];
+export const LUCY_MEMORY_TOOLS: readonly LucyMemoryToolDefinition[];
+export function safeMcpError(error: unknown, operation?: LucyMemoryToolName): McpSafeError;
+export function createLucyMemoryMcpServer(options: LucyMemoryMcpServerOptions): Promise<Server>;

package/src/mcp/lifecycle.mjs

@@ -0,0 +1,50 @@
+const SAFE_MESSAGES = Object.freeze({
+  CONFIGURATION_ERROR: 'Lucy Memory MCP configuration is invalid.',
+  TRANSPORT_LOAD_ERROR: 'Lucy Memory MCP transport could not be loaded.',
+  STARTUP_ERROR: 'Lucy Memory MCP could not start.',
+  SHUTDOWN_ERROR: 'Lucy Memory MCP could not shut down cleanly.',
+});
+
+export class McpLifecycleError extends Error {
+  constructor(code) {
+    super(SAFE_MESSAGES[code] ?? SAFE_MESSAGES.STARTUP_ERROR);
+    this.name = 'McpLifecycleError';
+    this.code = Object.hasOwn(SAFE_MESSAGES, code) ? code : 'STARTUP_ERROR';
+  }
+}
+
+export function safeLifecycleDiagnostic(error, fallback = 'STARTUP_ERROR') {
+  const fallbackCode = Object.hasOwn(SAFE_MESSAGES, fallback) ? fallback : 'STARTUP_ERROR';
+  const code = error instanceof McpLifecycleError && Object.hasOwn(SAFE_MESSAGES, error.code) ? error.code : fallbackCode;
+  return `${code}: ${SAFE_MESSAGES[code]}\n`;
+}
+
+export async function runLifecycleStage(code, action) {
+  try {
+    return await action();
+  } catch {
+    throw new McpLifecycleError(code);
+  }
+}
+
+export function createShutdownController({ close, writeDiagnostic, setExitCode }) {
+  if (typeof close !== 'function' || typeof writeDiagnostic !== 'function' || typeof setExitCode !== 'function') {
+    throw new TypeError('Shutdown controller dependencies must be functions.');
+  }
+  let pending;
+  return function shutdown() {
+    if (pending) return pending;
+    pending = (async () => {
+      try {
+        await close();
+        setExitCode(0);
+        return true;
+      } catch {
+        writeDiagnostic(safeLifecycleDiagnostic(new McpLifecycleError('SHUTDOWN_ERROR'), 'SHUTDOWN_ERROR'));
+        setExitCode(1);
+        return false;
+      }
+    })();
+    return pending;
+  };
+}

package/src/mcp/schemas.mjs

@@ -0,0 +1,98 @@
+import { readFileSync, readdirSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const BASE = 'https://schemas.trylucy.ai/agent-memory/v1/';
+const SCHEMA_DIRECTORY = fileURLToPath(new URL('../../schemas/v1/', import.meta.url));
+const CANONICAL_RECALL_OUTPUT = JSON.parse(readFileSync(new URL('../../schemas/canonical-recall/response.schema.json', import.meta.url), 'utf8'));
+const documents = new Map();
+for (const name of readdirSync(SCHEMA_DIRECTORY).filter((value) => value.endsWith('.schema.json')).sort()) {
+  const document = JSON.parse(readFileSync(new URL(`../../schemas/v1/${name}`, import.meta.url), 'utf8'));
+  if (document.$id !== `${BASE}${name}`) throw new Error(`Frozen schema identity mismatch: ${name}`);
+  documents.set(name.replace('.schema.json', ''), document);
+}
+
+function referenceTarget(reference, currentName) {
+  if (reference.startsWith('#')) return currentName;
+  if (!reference.startsWith(BASE)) throw new Error(`External frozen schema reference is not allowed: ${reference}`);
+  const relative = reference.slice(BASE.length);
+  const hash = relative.indexOf('#');
+  return (hash < 0 ? relative : relative.slice(0, hash)).replace('.schema.json', '');
+}
+function rewriteReference(reference, currentName) {
+  if (reference.startsWith('#')) return `#/$defs/${currentName}${reference.slice(1)}`;
+  const target = referenceTarget(reference, currentName);
+  if (!documents.has(target)) throw new Error(`Frozen schema reference not found: ${reference}`);
+  const hash = reference.indexOf('#');
+  return `#/$defs/${target}${hash < 0 ? '' : reference.slice(hash + 1)}`;
+}
+function transform(value, currentName) {
+  if (Array.isArray(value)) return value.map((item) => transform(item, currentName));
+  if (!value || typeof value !== 'object') return value;
+  const output = {};
+  for (const [key, child] of Object.entries(value)) {
+    if (key === '$id' || key === '$schema') continue;
+    output[key] = key === '$ref' ? rewriteReference(child, currentName) : transform(child, currentName);
+  }
+  return output;
+}
+function collectReferences(value, currentName, found) {
+  if (Array.isArray(value)) { for (const item of value) collectReferences(item, currentName, found); return; }
+  if (!value || typeof value !== 'object') return;
+  for (const [key, child] of Object.entries(value)) {
+    if (key === '$ref') {
+      const target = referenceTarget(child, currentName);
+      if (!found.has(target)) {
+        found.add(target);
+        collectReferences(documents.get(target), target, found);
+      }
+    } else collectReferences(child, currentName, found);
+  }
+}
+function definitionsFor(rootNames) {
+  const names = new Set(rootNames);
+  for (const name of rootNames) collectReferences(documents.get(name), name, names);
+  return Object.fromEntries([...names].sort().map((name) => [name, transform(documents.get(name), name)]));
+}
+function bundled(name) {
+  const definitions = definitionsFor([name]);
+  return { ...structuredClone(definitions[name]), $defs: definitions };
+}
+function deepFreeze(value) {
+  if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+    Object.freeze(value);
+    for (const child of Object.values(value)) deepFreeze(child);
+  }
+  return value;
+}
+
+const proposalDefinitions = definitionsFor(['create-proposal-request', 'replace-proposal-request']);
+const proposalBranch = (name) => {
+  const schema = structuredClone(proposalDefinitions[name]);
+  delete schema.$defs;
+  return schema;
+};
+const statusDefinitions = definitionsFor(['common']);
+export const MCP_SCHEMAS = deepFreeze({
+  recallInput: bundled('recall-request'),
+  proposalInput: {
+    type: 'object',
+    oneOf: [proposalBranch('create-proposal-request'), proposalBranch('replace-proposal-request')],
+    $defs: proposalDefinitions,
+  },
+  proposalStatusInput: {
+    type: 'object',
+    additionalProperties: false,
+    required: ['proposal_id'],
+    properties: { proposal_id: { $ref: '#/$defs/common/$defs/proposalId' } },
+    $defs: statusDefinitions,
+  },
+  recallOutput: bundled('recall-response'),
+  canonicalRecallOutput: CANONICAL_RECALL_OUTPUT,
+  proposalOutput: bundled('proposal-status'),
+});
+
+export function containsExternalSchemaReference(value) {
+  if (Array.isArray(value)) return value.some(containsExternalSchemaReference);
+  if (!value || typeof value !== 'object') return false;
+  return Object.entries(value).some(([key, child]) => (key === '$ref' && !String(child).startsWith('#')) || containsExternalSchemaReference(child));
+}

package/src/mcp/server.mjs

@@ -0,0 +1,163 @@
+import { ProtocolError, ProtocolErrorCode, Server } from '@modelcontextprotocol/server';
+import { types as utilTypes } from 'node:util';
+import { AgentMemoryClient, mappedErrorRequestId, safePublicErrorRequestId } from '../client/client.mjs';
+import {
+  AgentMemoryError,
+  AuthorizationFailureError,
+  ValidationFailureError,
+} from '../client/errors.mjs';
+import { stableSerialize } from '../client/serialization.mjs';
+import { MCP_SCHEMAS } from './schemas.mjs';
+import { usageSkillText } from '../onboarding/usage.mjs';
+
+export const LUCY_MEMORY_TOOL_NAMES = Object.freeze([
+  'memory_recall',
+  'memory_propose',
+  'memory_proposal_status',
+]);
+
+const SAFE_ERROR_MESSAGES = Object.freeze({
+  authentication_failure: 'Lucy authentication failed.',
+  authorization_failure: 'Lucy authorization failed.',
+  invalid_scope: 'The memory scope is invalid.',
+  invalid_key: 'The memory key is invalid.',
+  invalid_kind: 'The memory kind is invalid.',
+  validation_failure: 'The memory request is invalid.',
+  proposal_not_found: 'The proposal was not found or is not visible.',
+  memory_not_found: 'The memory was not found or is not visible.',
+  version_conflict: 'The expected memory version does not match.',
+  lifecycle_conflict: 'The memory lifecycle does not permit this operation.',
+  rate_limit: 'Lucy rate limited the request.',
+  upstream_unavailable: 'Lucy is temporarily unavailable.',
+  timeout: 'The Lucy request timed out.',
+  malformed_response: 'Lucy returned a malformed response.',
+  proposal_contract_incompatible: 'Lucy returned a proposal response incompatible with the frozen AM-01 contract. Ask the Lucy service operator to restore AM-01 compatibility, then retry.',
+  internal_lucy_error: 'Lucy returned an internal error.',
+  insufficient_credits: 'The workspace does not have enough Lucy credits for this Agent Memory operation.',
+  billing_unavailable: 'Lucy billing is temporarily unavailable.',
+});
+const SAFE_ERROR_CODES = new Set(Object.keys(SAFE_ERROR_MESSAGES));
+const RETRYABLE_ERROR_CODES = new Set(['rate_limit', 'upstream_unavailable', 'timeout', 'billing_unavailable']);
+const INTERNAL_MCP_ERROR = Object.freeze({
+  code: 'internal_mcp_error',
+  message: 'Lucy Memory MCP could not complete the request.',
+  retryable: false,
+  status: null,
+});
+const CANONICAL_CLIENT_OPERATIONS = Object.freeze({
+  memory_recall: AgentMemoryClient.prototype.recallCanonical,
+  memory_propose: AgentMemoryClient.prototype.propose,
+  memory_proposal_status: AgentMemoryClient.prototype.proposalStatus,
+});
+const AUTHORIZATION_FAILURE_PROTOTYPE = AuthorizationFailureError.prototype;
+const VALIDATION_FAILURE_PROTOTYPE = ValidationFailureError.prototype;
+const AGENT_MEMORY_CLIENT_PROTOTYPE = AgentMemoryClient.prototype;
+const BOUNDARY_TYPE_ERROR = TypeError;
+const GET_PROTOTYPE_OF = Object.getPrototypeOf;
+const IS_FROZEN = Object.isFrozen;
+const IS_PROXY = utilTypes.isProxy;
+const REFLECT_APPLY = Reflect.apply;
+
+export const LUCY_MEMORY_TOOLS = Object.freeze([
+  Object.freeze({
+    name: 'memory_recall',
+    description: 'Recall active approved Lucy memory only. Use for durable preferences, identity, project decisions, or explicit remember/recall. Do not use for arithmetic, weather, news, or one-shot drafting.',
+    annotations: Object.freeze({ readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: true }),
+    inputSchema: MCP_SCHEMAS.recallInput,
+    outputSchema: MCP_SCHEMAS.canonicalRecallOutput,
+  }),
+  Object.freeze({
+    name: 'memory_propose',
+    description: 'Propose a durable Lucy memory write. Success means pending, not saved. Do not send secrets. Humans approve on Lucy unless they enabled auto memory.',
+    annotations: Object.freeze({ readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true }),
+    inputSchema: MCP_SCHEMAS.proposalInput,
+    outputSchema: MCP_SCHEMAS.proposalOutput,
+  }),
+  Object.freeze({
+    name: 'memory_proposal_status',
+    description: 'Read whether a Lucy proposal is pending, approved, rejected, expired, or superseded. Pending memory is not recallable.',
+    annotations: Object.freeze({ readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: true }),
+    inputSchema: MCP_SCHEMAS.proposalStatusInput,
+    outputSchema: MCP_SCHEMAS.proposalOutput,
+  }),
+]);
+
+function ownDataValue(value, key) {
+  const descriptor = Object.getOwnPropertyDescriptor(value, key);
+  return descriptor && Object.hasOwn(descriptor, 'value') ? descriptor.value : undefined;
+}
+
+export function safeMcpError(error, operation) {
+  try {
+    if (!(error instanceof AgentMemoryError)) return { ...INTERNAL_MCP_ERROR };
+    const code = ownDataValue(error, 'code');
+    if (!SAFE_ERROR_CODES.has(code)) return { ...INTERNAL_MCP_ERROR };
+    const candidateStatus = ownDataValue(error, 'status');
+    const status = Number.isInteger(candidateStatus) && candidateStatus >= 100 && candidateStatus <= 599
+      ? candidateStatus
+      : null;
+    const requestId = safePublicErrorRequestId(mappedErrorRequestId(error));
+    return {
+      code,
+      message: SAFE_ERROR_MESSAGES[code],
+      retryable: operation === 'memory_propose' && RETRYABLE_ERROR_CODES.has(code),
+      status,
+      ...(requestId === null ? {} : { request_id: requestId }),
+    };
+  } catch {
+    return { ...INTERNAL_MCP_ERROR };
+  }
+}
+
+async function requireClient(client) {
+  try {
+    if (IS_PROXY(client)
+      || GET_PROTOTYPE_OF(client) !== AGENT_MEMORY_CLIENT_PROTOTYPE
+      || !IS_FROZEN(client)) {
+      throw new BOUNDARY_TYPE_ERROR('client must be an exact non-proxy AgentMemoryClient.');
+    }
+    await REFLECT_APPLY(CANONICAL_CLIENT_OPERATIONS.memory_recall, client, ['{']);
+    throw new BOUNDARY_TYPE_ERROR('client must be an exact non-proxy AgentMemoryClient.');
+  } catch (error) {
+    const errorPrototype = IS_PROXY(error) ? null : GET_PROTOTYPE_OF(error);
+    if (errorPrototype === AUTHORIZATION_FAILURE_PROTOTYPE
+      || errorPrototype === VALIDATION_FAILURE_PROTOTYPE) return client;
+    throw new BOUNDARY_TYPE_ERROR('client must be an exact non-proxy AgentMemoryClient.');
+  }
+}
+
+export async function createLucyMemoryMcpServer({ client, name = 'lucy-memory-mcp', version = '0.1.2' } = {}) {
+  const memoryClient = await requireClient(client);
+  const server = new Server(
+    { name, version },
+    { capabilities: { tools: {} }, instructions: usageSkillText() },
+  );
+
+  server.setRequestHandler('tools/list', async () => ({ tools: LUCY_MEMORY_TOOLS }));
+  server.setRequestHandler('tools/call', async ({ params }) => {
+    const argumentsJson = stableSerialize(params.arguments ?? {});
+    try {
+      const operation = CANONICAL_CLIENT_OPERATIONS[params.name];
+      if (operation === undefined) throw new ProtocolError(ProtocolErrorCode.InvalidParams, `Unknown tool: ${params.name}`);
+      const result = await REFLECT_APPLY(operation, memoryClient, [argumentsJson]);
+      // Keep billing correlation in tool text for acceptance/agents. Strip it from
+      // structuredContent so frozen AM-01 outputSchema (additionalProperties:false) still validates.
+      const { operation_id: _billingOperationId, ...am01Structured } = result && typeof result === 'object' && !Array.isArray(result)
+        ? result
+        : { ...(result ?? {}) };
+      return {
+        content: [{ type: 'text', text: stableSerialize(result) }],
+        structuredContent: am01Structured,
+      };
+    } catch (error) {
+      if (error instanceof ProtocolError) throw error;
+      const payload = safeMcpError(error, params.name);
+      return {
+        isError: true,
+        content: [{ type: 'text', text: stableSerialize(payload) }],
+      };
+    }
+  });
+
+  return server;
+}

package/src/mcp/stdio.d.ts

@@ -0,0 +1,28 @@
+import type { Readable, Writable } from 'node:stream';
+import type { AgentMemoryClient } from '../client/index.js';
+
+export interface LucyMemoryStdioRuntime {
+  readonly close: () => Promise<void>;
+}
+export interface LucyMemoryStdioOptions {
+  client: AgentMemoryClient;
+  stdin?: Readable;
+  stdout?: Writable;
+  maxBufferSize?: number;
+}
+export function modulePathFromUrl(url: URL | string): string;
+export function startLucyMemoryMcpStdio(options: LucyMemoryStdioOptions): Promise<LucyMemoryStdioRuntime>;
+export function runLucyMemoryMcpStdio(options?: {
+  environment?: Record<string, string | undefined>;
+  stdin?: Readable;
+  stdout?: Writable;
+}): Promise<LucyMemoryStdioRuntime>;
+export function main(options?: {
+  environment?: Record<string, string | undefined>;
+  stdin?: Readable;
+  stdout?: Writable;
+  stderr?: Writable;
+  exit?: (code: number) => void;
+  signals?: { once(event: 'SIGINT' | 'SIGTERM', listener: () => void): unknown };
+  runtimeFactory?: typeof runLucyMemoryMcpStdio;
+}): Promise<(LucyMemoryStdioRuntime & { readonly shutdown: () => Promise<boolean> }) | null>;

package/src/mcp/stdio.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+import { StdioServerTransport, serveStdio } from '@modelcontextprotocol/server/stdio';
+import { fileURLToPath } from 'node:url';
+import { AgentMemoryClient } from '../client/client.mjs';
+import { loadLucyMemoryMcpConfig, resolveLucyMemoryTransport } from './config.mjs';
+import { createShutdownController, runLifecycleStage, safeLifecycleDiagnostic } from './lifecycle.mjs';
+import { createLucyMemoryMcpServer } from './server.mjs';
+
+export function modulePathFromUrl(url) {
+  return fileURLToPath(url);
+}
+
+export async function startLucyMemoryMcpStdio({ client, stdin = process.stdin, stdout = process.stdout, maxBufferSize = 1_048_576 } = {}) {
+  const transport = new StdioServerTransport(stdin, stdout, { maxBufferSize });
+  const handle = serveStdio(
+    () => createLucyMemoryMcpServer({ client }),
+    { transport, legacy: 'serve' },
+  );
+  return Object.freeze({ close: async () => handle.close() });
+}
+
+export async function runLucyMemoryMcpStdio({ environment = process.env, stdin = process.stdin, stdout = process.stdout } = {}) {
+  const config = await runLifecycleStage('CONFIGURATION_ERROR', () => loadLucyMemoryMcpConfig(environment));
+  const transport = await runLifecycleStage('TRANSPORT_LOAD_ERROR', () => resolveLucyMemoryTransport(config));
+  const client = new AgentMemoryClient({
+    transport,
+    token: config.token,
+    permissions: config.permissions,
+    timeoutMs: config.timeoutMs,
+  });
+  return runLifecycleStage('STARTUP_ERROR', () => startLucyMemoryMcpStdio({ client, stdin, stdout }));
+}
+
+export async function main({ environment = process.env, stdin = process.stdin, stdout = process.stdout, stderr = process.stderr,
+  exit = (code) => process.exit(code), signals = process, runtimeFactory = runLucyMemoryMcpStdio } = {}) {
+  let runtime;
+  try {
+    runtime = await runtimeFactory({ environment, stdin, stdout });
+  } catch (error) {
+    stderr.write(safeLifecycleDiagnostic(error));
+    exit(1);
+    return null;
+  }
+  let shutdownExitCode = 1;
+  const shutdown = createShutdownController({
+    close: runtime.close,
+    writeDiagnostic: (diagnostic) => stderr.write(diagnostic),
+    setExitCode: (code) => { shutdownExitCode = code; },
+  });
+  let signalHandled = false;
+  const onSignal = () => {
+    if (signalHandled) return;
+    signalHandled = true;
+    shutdown().finally(() => exit(shutdownExitCode));
+  };
+  signals.once('SIGINT', onSignal);
+  signals.once('SIGTERM', onSignal);
+  return Object.freeze({ ...runtime, shutdown });
+}

package/src/onboarding/usage.mjs

@@ -0,0 +1,44 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const manifest = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), '../../contracts/agent-manifest.json'), 'utf8'));
+
+export const LUCY_USAGE_SKILL = `# Lucy governed memory
+
+${manifest.sentence}
+
+Use exactly these tools:
+
+- memory_recall: active approved Lucy memory only
+- memory_propose: request a durable write; this is not a save
+- memory_proposal_status: inspect pending/approved/rejected
+
+Do not invent a fourth tool. Do not approve, deny, forget, or restore through MCP.
+
+Recall when a durable preference, identity fact, project decision, or explicit remember/recall request matters.
+Do not recall for arithmetic, weather, news, or one-shot drafting.
+
+Search recall practically:
+
+- Scope is an object, never a string: user \`{ "kind": "user" }\`, workspace \`{ "kind": "workspace" }\`, project \`{ "kind": "project", "id": "<project-id>" }\`.
+- Minimal valid request: \`{ "query": "database", "scope": { "kind": "user" } }\`.
+- Begin with concise literal, distinctive substrings rather than a long paraphrase.
+- Try spelling and spacing variants.
+- Use known keys, kinds, and scopes when available.
+- Broaden or narrow the query and filters iteratively.
+- Do not conclude that memory is absent after one empty result.
+- Distinguish a successful recall with zero matches from authentication, authorization, or service errors.
+
+Propose only durable non-secret facts. Pending is not recallable. Wait for Lucy/human approval unless the human enabled auto memory on Lucy.
+
+Local notes are not Lucy authority. If they conflict, Lucy wins. Never dual-write.
+`;
+
+export function usageSkillText() {
+  return LUCY_USAGE_SKILL;
+}
+
+export function publicManifest() {
+  return manifest;
+}