@pyxmate/memory 0.1.0-beta → 0.1.1-beta

package/README.md

@@ -10,6 +10,16 @@ Provides an HTTP client, shared types, and optional dashboard + React hooks for
 npm install @pyxmate/memory
 ```
 
+## Setup Claude Code Skills
+
+If you use [Claude Code](https://docs.anthropic.com/en/docs/claude-code), run this command to install pyx-memory integration skills:
+
+```bash
+npx @pyxmate/memory init
+```
+
+This copies skill files into `.claude/skills/pyx-memory-integration/` so Claude Code auto-discovers pyx-memory patterns, types, and API reference when working in your project.
+
 ## Usage
 
 ```ts

package/bin/init.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+
+import { cpSync, existsSync, mkdirSync, readdirSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const command = process.argv[2];
+
+if (command !== 'init') {
+  console.log(`Usage: pyxmate-memory init
+
+Commands:
+  init    Copy pyx-memory skill files into .claude/skills/ for Claude Code auto-discovery`);
+  process.exit(command ? 1 : 0);
+}
+
+const source = resolve(__dirname, '..', 'skills', 'pyx-memory-integration');
+const target = resolve(process.cwd(), '.claude', 'skills', 'pyx-memory-integration');
+
+if (!existsSync(source)) {
+  console.error('Error: Skills directory not found in package. Please reinstall @pyxmate/memory.');
+  process.exit(1);
+}
+
+// Ensure target parent exists
+mkdirSync(dirname(target), { recursive: true });
+
+// Copy skills (overwrites existing files for idempotency)
+cpSync(source, target, { recursive: true });
+
+// Count copied files
+function countFiles(dir) {
+  let count = 0;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      count += countFiles(join(dir, entry.name));
+    } else {
+      count++;
+    }
+  }
+  return count;
+}
+
+function listFiles(dir, prefix = '') {
+  const lines = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      lines.push(...listFiles(join(dir, entry.name), `${prefix}${entry.name}/`));
+    } else {
+      lines.push(`  ${prefix}${entry.name}`);
+    }
+  }
+  return lines;
+}
+
+const fileCount = countFiles(target);
+const fileList = listFiles(target);
+
+console.log(`Copied ${fileCount} skill files to .claude/skills/pyx-memory-integration/\n`);
+console.log(fileList.join('\n'));
+console.log('\nClaude Code will now auto-discover pyx-memory integration patterns.');

package/dist/{chunk-VJGRAIVX.mjs → chunk-JMXAZPDT.mjs}

@@ -13,15 +13,20 @@ var MemoryServerError = class extends Error {
 };
 var MemoryClient = class {
   baseUrl;
-  constructor(memoryUrl) {
+  _authHeaders;
+  constructor(memoryUrl, apiKey) {
     this.baseUrl = memoryUrl.replace(/\/$/, "");
+    const trimmed = apiKey?.trim();
+    this._authHeaders = trimmed ? { Authorization: `Bearer ${trimmed}` } : {};
   }
   /** Encode a path segment to prevent URL injection */
   encodePathSegment(segment) {
     return encodeURIComponent(segment);
   }
   async initialize() {
-    const response = await fetch(`${this.baseUrl}/health`);
+    const response = await fetch(`${this.baseUrl}/health`, {
+      headers: this._authHeaders
+    });
     if (!response.ok) {
       throw new Error(`Memory server not reachable at ${this.baseUrl}: ${response.status}`);
     }
@@ -92,7 +97,8 @@ var MemoryClient = class {
     formData.append("file", file);
     const res = await fetch(`${this.baseUrl}/api/memory/ingest/file`, {
       method: "POST",
-      body: formData
+      body: formData,
+      headers: this._authHeaders
     });
     const body = await res.json();
     if (!body.success || body.data === void 0) {
@@ -194,7 +200,8 @@ var MemoryClient = class {
       ...options,
       headers: {
         "Content-Type": "application/json",
-        ...options?.headers
+        ...options?.headers,
+        ...this._authHeaders
       }
     });
     const body = await res.json();

package/dist/{chunk-ACMIMR43.mjs → chunk-XNKO7F3P.mjs}

@@ -1,6 +1,6 @@
 import {
   MemoryClient
-} from "./chunk-VJGRAIVX.mjs";
+} from "./chunk-JMXAZPDT.mjs";
 
 // ../dashboard/src/aggregations/consolidation-analytics.ts
 function analyzeConsolidationLog(entries) {

package/dist/dashboard.mjs

@@ -11,8 +11,8 @@ import {
   toGraphologyFormat,
   transformGraphData,
   unreachableHealth
-} from "./chunk-ACMIMR43.mjs";
-import "./chunk-VJGRAIVX.mjs";
+} from "./chunk-XNKO7F3P.mjs";
+import "./chunk-JMXAZPDT.mjs";
 export {
   DashboardClient,
   Poller,

package/dist/index.d.ts

@@ -82,7 +82,8 @@ declare class MemoryServerError extends Error {
 }
 declare class MemoryClient implements ExtendedMemoryInterface {
     protected baseUrl: string;
-    constructor(memoryUrl: string);
+    private readonly _authHeaders;
+    constructor(memoryUrl: string, apiKey?: string);
     /** Encode a path segment to prevent URL injection */
     private encodePathSegment;
     initialize(): Promise<void>;

package/dist/index.mjs

@@ -1,7 +1,7 @@
 import {
   MemoryClient,
   MemoryServerError
-} from "./chunk-VJGRAIVX.mjs";
+} from "./chunk-JMXAZPDT.mjs";
 
 // ../shared/src/constants/defaults.ts
 var DEFAULTS = {

package/dist/react.mjs

@@ -11,8 +11,8 @@ import {
   toGraphologyFormat,
   transformGraphData,
   unreachableHealth
-} from "./chunk-ACMIMR43.mjs";
-import "./chunk-VJGRAIVX.mjs";
+} from "./chunk-XNKO7F3P.mjs";
+import "./chunk-JMXAZPDT.mjs";
 
 // ../dashboard/src/hooks/use-consolidation-log.ts
 import { useCallback as useCallback2, useMemo } from "react";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyxmate/memory",
-  "version": "0.1.0-beta",
+  "version": "0.1.1-beta",
   "type": "module",
   "description": "SDK for pyx-memory — Memory as a Service for AI agents",
   "license": "MIT",
@@ -33,15 +33,21 @@
       "types": "./dist/react.d.ts"
     }
   },
+  "bin": {
+    "pyxmate-memory": "./bin/init.mjs"
+  },
   "files": [
     "dist",
+    "bin",
+    "skills",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsup",
+    "copy-skills": "rm -rf skills/pyx-memory-integration && mkdir -p skills && cp -r ../../.claude/skills/pyx-memory-integration skills/pyx-memory-integration && rm -rf skills/pyx-memory-integration/scripts",
+    "build": "bun run copy-skills && tsup",
     "typecheck": "tsc --noEmit",
-    "clean": "rm -rf dist node_modules .turbo"
+    "clean": "rm -rf dist skills node_modules .turbo"
   },
   "peerDependencies": {
     "react": ">=18.0.0"

package/skills/pyx-memory-integration/SKILL.md

@@ -0,0 +1,266 @@
+---
+name: pyx-memory-integration
+description: >
+  Integration guide for the pyx-memory universal memory system (TypeScript/Bun).
+  Use when integrating pyx-memory into a project, migrating to pyx-memory,
+  setting up embedded or sidecar memory, asking about pyx-memory API or types,
+  configuring RAG strategies, file ingestion, or lifecycle management.
+  Triggers on: 'integrate pyx-memory', 'add memory system', 'setup pyx-memory',
+  'memory store search', 'MemoryInterface', 'EmbeddingProvider', 'createMemory',
+  'pyx-memory configuration', 'memory consolidation', 'graph RAG'.
+---
+
+# pyx-memory — AI Agent Integration Guide
+
+Reference for AI agents integrating pyx-memory into TypeScript/Bun projects.
+Runtime requirement: **Bun v1.2+** (not Node.js). Uses `bun:sqlite` natively.
+
+> After integration work, run the diagnostic tool to verify correctness:
+> ```bash
+> bun .claude/skills/pyx-memory-integration/scripts/diagnose-integration.ts --json
+> ```
+> Parse the `verdict` field: `"healthy"` = done, otherwise fix each `criticalIssues` entry and re-run.
+
+---
+
+## What are you trying to do?
+
+**Integrate pyx-memory into a consumer project?**
+  → See [patterns/consumer.md](patterns/consumer.md)
+
+**Set up embedded memory with full features?**
+  → See [patterns/embedded.md](patterns/embedded.md)
+
+**Understand type signatures and interfaces?**
+  → See [reference/types.md](reference/types.md)
+
+**Check sidecar limitations before choosing a mode?**
+  → See [reference/parity.md](reference/parity.md)
+
+**Use the HTTP API directly?**
+  → See [reference/http-api.md](reference/http-api.md)
+
+**Configure RAG, bi-temporal queries, or consolidation?**
+  → See [reference/advanced.md](reference/advanced.md)
+
+**Validate your integration setup?**
+  → Run: `bun .claude/skills/pyx-memory-integration/scripts/diagnose-integration.ts`
+
+**Check server connectivity?**
+  → Run: `bun .claude/skills/pyx-memory-integration/scripts/diagnose-integration.ts --phase=runtime`
+
+**Get machine-readable diagnostic report?**
+  → Run: `bun .claude/skills/pyx-memory-integration/scripts/diagnose-integration.ts --json`
+
+---
+
+## Quick Decision Tree
+
+```
+Building pyx-memory itself or its server?
+  → Embedded mode: import { Memory } from '@pyx-memory/core'
+
+Consuming pyx-memory from another project (e.g., agent-forge)?
+  → Sidecar mode: import { MemoryClient } from '@pyx-memory/client'
+  → ONLY depend on @pyx-memory/client + @pyx-memory/shared
+  → Do NOT import @pyx-memory/core — that's pyx-memory's internal implementation
+  → See patterns/consumer.md
+
+Need memory in your process (best perf, full feature set)?
+  → Embedded mode: import { Memory } from '@pyx-memory/core'
+
+Need memory as a separate service (HTTP)?
+  → Sidecar mode: import { MemoryClient } from '@pyx-memory/client'
+
+Need to switch modes via config?
+  → Factory: import { createMemory } from '@pyx-memory/core'
+    - Returns MemoryInterface (base interface — no lifecycle methods)
+    - If you need consolidate/decay/summarize, use `new Memory()` directly
+
+Need lifecycle methods (consolidate, decay, summarize)?
+  → Use `new Memory(opts)` — returns ExtendedMemoryInterface
+  → Or `new MemoryClient(url)` — also implements ExtendedMemoryInterface
+  → NOT createMemory() — it returns MemoryInterface (missing lifecycle methods)
+
+Need dashboard features (consolidation log, graph visualization)?
+  → Use `DashboardClient` from '@pyx-memory/dashboard'
+  → Extends MemoryClient with additional methods
+```
+
+---
+
+## Minimal Working Example (Embedded)
+
+```typescript
+import { Memory } from '@pyx-memory/core';
+
+// Embedding is internal — pyx-memory uses BGE-M3 (1024d) automatically
+const memory = new Memory({ dataDir: './data' });
+await memory.initialize(); // REQUIRED — throws if you skip this
+
+// Store (default targets: sqlite + vector)
+await memory.store({
+  content: 'User prefers dark mode',
+  type: 'long-term',
+  metadata: { source: 'settings' },
+});
+
+// Store with graph routing (agent provides entities)
+await memory.store({
+  content: 'Alice works at Acme Corp',
+  type: 'long-term',
+  metadata: {},
+  targets: ['sqlite', 'vector', 'graph'],
+  entities: [
+    { name: 'Alice', type: 'PERSON' },
+    { name: 'Acme Corp', type: 'ORGANIZATION' },
+  ],
+  relationships: [{ source: 'Alice', target: 'Acme Corp', type: 'WORKS_AT' }],
+});
+
+// Search
+const results = await memory.search({ query: 'user preferences', limit: 5 });
+
+// Cleanup
+await memory.shutdown(); // REQUIRED — releases SQLite + LanceDB resources
+```
+
+## Minimal Working Example (Sidecar / HTTP)
+
+```typescript
+import { MemoryClient } from '@pyx-memory/client';
+
+// Without auth (local dev)
+const memory = new MemoryClient('http://localhost:7822');
+
+// With auth (production — pass API key as second argument)
+const authedMemory = new MemoryClient('http://localhost:7822', process.env.MEMORY_API_KEY);
+
+await memory.initialize(); // verifies server connectivity via /health
+
+await memory.store({ content: 'Important fact', type: 'long-term', metadata: {} });
+const results = await memory.search({ query: 'fact', limit: 5 });
+```
+
+Start the server: `bun packages/server/src/index.ts`
+
+---
+
+## Package Map
+
+```
+@pyx-memory/shared   → Types + constants only (zero runtime code)
+       ↑       ↑
+       |       |
+@pyx-memory/client   → MemoryInterface, ExtendedMemoryInterface, MemoryClient
+       ↑
+       |
+@pyx-memory/core     → Memory class, embeddings, graph, RAG, ingestion, lifecycle
+       ↑                (re-exports everything from client and shared)
+       |
+@pyx-memory/server   → HTTP sidecar server (23 endpoints)
+
+@pyx-memory/dashboard → DashboardClient (extends MemoryClient), React hooks,
+                         Poller, aggregations, graph transforms (D3/Graphology)
+```
+
+**Import rules:**
+- **Embedded mode**: Import everything from `@pyx-memory/core` (it re-exports client + shared)
+- **Sidecar mode (client only)**: Import from `@pyx-memory/client` (+ types from `@pyx-memory/shared`)
+- **Dashboard features**: Import from `@pyx-memory/dashboard` (extends client with extra methods)
+- **Types only**: Import from `@pyx-memory/shared`
+- **Consumer projects**: ONLY use `@pyx-memory/client` + `@pyx-memory/shared` — never `@pyx-memory/core`
+
+For full type definitions and interfaces, see [reference/types.md](reference/types.md).
+
+For HTTP API endpoint reference, see [reference/http-api.md](reference/http-api.md).
+
+For feature parity between embedded and sidecar modes, see [reference/parity.md](reference/parity.md).
+
+For RAG strategies, bi-temporal model, consolidation, and community detection, see [reference/advanced.md](reference/advanced.md).
+
+---
+
+## DO / DON'T
+
+### DO
+
+- **DO** call `await memory.initialize()` before any operation
+- **DO** call `await memory.shutdown()` when done (releases SQLite + LanceDB)
+- **DO** provide `entities` when using `targets: ['graph']` — graph storage requires agent-provided entities
+- **DO** initialize GraphStore BEFORE constructing Memory
+- **DO** use `new Memory()` when you need lifecycle methods (ExtendedMemoryInterface)
+- **DO** use `':memory:'` dataDir for tests
+- **DO** handle `MemoryServerError` in sidecar mode (has `.status` and `.isNotFound`)
+- **DO** use `MemoryClient` (not `MemoryInterface`) when you need graph or file ingestion — these are concrete methods
+- **DO** use `DashboardClient` when you need consolidation logs, graph relationships, or enriched health data
+- **DO** implement `DisabledMemory` (no-op) in consumer projects for graceful degradation when memory is unavailable
+
+### DON'T
+
+- **DON'T** assume `createMemory()` returns `ExtendedMemoryInterface` — it returns `MemoryInterface`
+- **DON'T** use `targets: ['graph']` without entities — throws MemoryError
+- **DON'T** use `targets: ['graph']` without a configured `graphStore` — throws MemoryError
+- **DON'T** use `strategy: 'graph'` without passing `graphStore` — throws "RAG strategy not registered"
+- **DON'T** use `strategy: 'agentic'` without passing `reasoningProvider`
+- **DON'T** construct multiple Memory instances with the same `dataDir` — LanceDB singleton causes conflicts
+- **DON'T** use `':memory:'` in production — LanceDB still writes to `/tmp/autonomy-vectors`
+- **DON'T** expose the server without configuring `API_KEY` for network deployments — use an API gateway for internet-facing deployments
+- **DON'T** import `@pyx-memory/core` in consumer projects — use `@pyx-memory/client` for clean separation
+- **DON'T** expect `filters`, `enableHyDE`, or `enableRerank` to work in sidecar mode — the HTTP API doesn't forward them
+
+---
+
+## AI Agent Post-Integration Checklist
+
+After integrating pyx-memory, run the diagnostic tool to verify everything is wired correctly:
+
+```bash
+bun .claude/skills/pyx-memory-integration/scripts/diagnose-integration.ts --json
+```
+
+**Interpret the result:**
+1. Parse the JSON `verdict` field:
+   - `"healthy"` → Integration is complete and working
+   - `"misconfigured"` → Environment or config issues — fix each item in `criticalIssues`
+   - `"broken"` → Server is down or unreachable — start the server first
+   - `"degraded"` → Working but with warnings (e.g., stub embeddings)
+2. For each entry in `criticalIssues`, apply the `fix` instruction
+3. Re-run until `verdict === "healthy"`
+
+**Common failure: DisabledMemory (no-op)**
+If `MEMORY_URL` is not set, the client will silently fall back to a DisabledMemory no-op implementation. Everything appears to work (store returns success, health reports "ok") but nothing is actually persisted. The diagnostic tool detects this via checks S5 (missing URL) and I1 (empty store ID).
+
+---
+
+## Error Types
+
+```
+MemoryError (base)
+├── MemoryStoreError        — SQLite store failures
+├── MemoryNotFoundError     — entry not found
+├── MemorySearchError       — search failures
+├── VectorProviderError     — LanceDB/vector issues
+├── EmbeddingError          — embedding generation failures
+├── MigrationError          — schema migration issues
+├── IngestionError          — file parsing / ingestion failures
+├── LifecycleError          — consolidation / decay failures
+└── GraphError              — graph store operations
+
+MemoryServerError           — HTTP client errors (has .status, .isNotFound)
+```
+
+All from `@pyx-memory/core` except `MemoryServerError` from `@pyx-memory/client`.
+
+---
+
+## Copy-Paste Examples
+
+- [examples/minimal-embedded.ts](examples/minimal-embedded.ts) — Embedded setup with store/search/shutdown
+- [examples/minimal-sidecar.ts](examples/minimal-sidecar.ts) — Sidecar HTTP client setup
+- [examples/disabled-memory.ts](examples/disabled-memory.ts) — No-op DisabledMemory class for graceful degradation
+
+## Further Reading
+
+- `docs/ARCHITECTURE.md` — Deep architecture reference, research sources, cost analysis, competitive positioning
+- `README.md` — Project overview, HTTP API examples, deployment guides, Docker setup

package/skills/pyx-memory-integration/examples/disabled-memory.ts

@@ -0,0 +1,53 @@
+import type { MemoryInterface, MemoryListResult } from '@pyx-memory/client';
+import type { MemoryEntry, MemorySearchResult, MemoryStats } from '@pyx-memory/shared';
+
+export class DisabledMemory implements MemoryInterface {
+  async initialize(): Promise<void> {
+    console.warn('Memory service not configured — running without memory');
+  }
+  async store(
+    entry: Omit<MemoryEntry, 'id' | 'createdAt'> & { id?: string; createdAt?: string },
+  ): Promise<MemoryEntry> {
+    return {
+      id: '',
+      content: entry.content,
+      type: entry.type,
+      metadata: {},
+      createdAt: new Date().toISOString(),
+    };
+  }
+  async search(): Promise<MemorySearchResult> {
+    return { entries: [], totalCount: 0, strategy: 'naive' };
+  }
+  async list(): Promise<MemoryListResult> {
+    return { entries: [], totalCount: 0, page: 1, limit: 20 };
+  }
+  async get(): Promise<MemoryEntry | null> {
+    return null;
+  }
+  async delete(): Promise<boolean> {
+    return false;
+  }
+  async clearSession(): Promise<number> {
+    return 0;
+  }
+  async stats(): Promise<MemoryStats> {
+    return {
+      totalEntries: 0,
+      storageUsedBytes: 0,
+      vectorCount: 0,
+      recentAccessCount: 0,
+      connected: false,
+    };
+  }
+  async shutdown(): Promise<void> {}
+}
+
+// Usage: pick the right implementation based on config
+import { MemoryClient } from '@pyx-memory/client';
+
+const memory: MemoryInterface = process.env.MEMORY_URL
+  ? new MemoryClient(process.env.MEMORY_URL, process.env.MEMORY_API_KEY)
+  : new DisabledMemory();
+
+await memory.initialize();

package/skills/pyx-memory-integration/examples/minimal-embedded.ts

@@ -0,0 +1,25 @@
+import { Memory } from '@pyx-memory/core';
+
+const memory = new Memory({ dataDir: './data' });
+await memory.initialize(); // REQUIRED — throws if you skip this
+
+// Store (default targets: sqlite + vector)
+await memory.store({
+  content: 'User prefers dark mode',
+  type: 'long-term',
+  metadata: { source: 'settings' },
+});
+
+// Store with explicit targets (e.g., sqlite only)
+await memory.store({
+  content: 'Temporary working note',
+  type: 'working',
+  metadata: {},
+  targets: ['sqlite'],
+});
+
+// Search
+const _results = await memory.search({ query: 'user preferences', limit: 5 });
+
+// Cleanup
+await memory.shutdown(); // REQUIRED — releases SQLite + LanceDB resources

package/skills/pyx-memory-integration/examples/minimal-sidecar.ts

@@ -0,0 +1,14 @@
+import { MemoryClient } from '@pyx-memory/client';
+
+// Without auth (local dev)
+const memory = new MemoryClient('http://localhost:7822');
+
+// With auth (production — pass API key as second argument)
+// const memory = new MemoryClient('http://localhost:7822', process.env.MEMORY_API_KEY);
+
+await memory.initialize(); // verifies server connectivity via /health
+
+await memory.store({ content: 'Important fact', type: 'long-term', metadata: {} });
+const _results = await memory.search({ query: 'fact', limit: 5 });
+
+// Start the server: bun packages/server/src/index.ts

package/skills/pyx-memory-integration/patterns/consumer.md

@@ -0,0 +1,103 @@
+# Consumer Integration Patterns
+
+For downstream projects that **consume** pyx-memory (e.g., agent-forge, custom AI agents).
+
+**Rule: Only depend on `@pyx-memory/client` + `@pyx-memory/shared`. Never import `@pyx-memory/core`.**
+
+`@pyx-memory/core` is pyx-memory's internal implementation (SQLiteStore, LanceDB, embedding providers,
+RAG engines, graph stores). Importing it creates tight coupling — any internal change can break your project.
+
+---
+
+## Pattern 8: Consumer (Sidecar-Only)
+
+```typescript
+import { MemoryClient, MemoryServerError } from '@pyx-memory/client';
+import type { MemoryInterface, ExtendedMemoryInterface } from '@pyx-memory/client';
+import type { MemoryEntry, MemorySearchResult } from '@pyx-memory/shared';
+
+const MEMORY_URL = process.env.MEMORY_URL; // e.g., 'http://localhost:7822'
+
+let memory: MemoryClient | null = null;
+
+if (MEMORY_URL) {
+  memory = new MemoryClient(MEMORY_URL, process.env.MEMORY_API_KEY);
+  await memory.initialize(); // verifies connectivity
+}
+
+// Use memory if available
+if (memory) {
+  await memory.store({ content: 'fact', type: 'long-term', metadata: {} });
+  const results = await memory.search({ query: 'fact', limit: 5 });
+
+  // Graph queries — available on MemoryClient directly (no @pyx-memory/core needed)
+  const nodes = await memory.graphNodes();
+  const traversal = await memory.graphQuery({ nodeId: 'node-1', depth: 2 });
+
+  // File ingestion — also available on MemoryClient
+  const file = new File([buffer], 'report.pdf', { type: 'application/pdf' });
+  const result = await memory.ingestFile(file);
+
+  // Lifecycle
+  await memory.consolidate();
+  await memory.runDecay();
+}
+```
+
+---
+
+## Pattern 9: Graceful Degradation (DisabledMemory)
+
+When your project should work with or without pyx-memory, implement a no-op wrapper.
+See [examples/disabled-memory.ts](../examples/disabled-memory.ts) for a copy-paste ready implementation.
+
+```typescript
+import { MemoryClient } from '@pyx-memory/client';
+
+const memory: MemoryInterface = process.env.MEMORY_URL
+  ? new MemoryClient(process.env.MEMORY_URL, process.env.MEMORY_API_KEY)
+  : new DisabledMemory();
+
+await memory.initialize();
+```
+
+---
+
+## Health Endpoint Pattern
+
+Report memory status in your app's health check:
+
+```typescript
+// In your health route
+const memoryStatus = process.env.MEMORY_URL
+  ? { status: 'connected', url: process.env.MEMORY_URL }
+  : { status: 'disabled' };
+```
+
+---
+
+## Adding as Sidecar (Docker)
+
+```yaml
+# docker-compose.yaml
+services:
+  memory:
+    build:
+      context: ./vendor/pyx-memory
+      dockerfile: docker/Dockerfile
+    ports:
+      - "7822:7822"
+    volumes:
+      - memory-data:/data
+    environment:
+      - DATA_DIR=/data
+      # Embedding is internal (BGE-M3, 1024d) — no API keys needed
+      # - EMBEDDING_DIMENSIONS=1024  # optional override
+
+  your-app:
+    environment:
+      - MEMORY_URL=http://memory:7822
+
+volumes:
+  memory-data:
+```