@pyxmate/memory 0.0.5-beta → 0.1.1-beta

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:
+```

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

@@ -0,0 +1,223 @@
+# Embedded Integration Patterns
+
+For projects using pyx-memory directly in-process with full feature access.
+
+## Contents
+- [Pattern 1: Testing / Development](#pattern-1-testing--development)
+- [Pattern 2: Production](#pattern-2-production)
+- [Pattern 3: Production with Store Targets](#pattern-3-production-with-store-targets)
+- [Pattern 4: With Knowledge Graph](#pattern-4-with-knowledge-graph)
+- [Pattern 5: With LLM Lifecycle](#pattern-5-with-llm-lifecycle)
+- [Pattern 6: File Ingestion](#pattern-6-file-ingestion)
+- [Pattern 7: Factory with Auto-Mode Switching](#pattern-7-factory-with-auto-mode-switching)
+- [Adding as Git Submodule](#adding-as-git-submodule-recommended-for-embedded-mode)
+- [MemoryOptions Quick Reference](#memoryoptions-quick-reference)
+
+---
+
+## Pattern 1: Testing / Development
+
+```typescript
+import { Memory } from '@pyx-memory/core';
+
+const memory = new Memory({ dataDir: ':memory:' });
+await memory.initialize();
+// Memory internally creates a LocalEmbeddingProvider (BGE-M3, 1024d)
+// No embedder needed — embedding is fully managed
+```
+
+## Pattern 2: Production
+
+```typescript
+import { Memory } from '@pyx-memory/core';
+
+const memory = new Memory({ dataDir: './data' });
+await memory.initialize();
+// Embedding is handled internally by LocalEmbeddingProvider (BGE-M3 via @huggingface/transformers, 1024d)
+// No external embedding provider needed
+```
+
+## Pattern 3: Production with Store Targets
+
+```typescript
+import { Memory } from '@pyx-memory/core';
+
+const memory = new Memory({ dataDir: './data' });
+await memory.initialize();
+
+// Default: stores to sqlite + vector
+await memory.store({
+  content: 'User prefers dark mode',
+  type: 'long-term',
+  metadata: { source: 'settings' },
+});
+
+// Explicit targets: sqlite only (skip vector indexing)
+await memory.store({
+  content: 'Temporary note',
+  type: 'working',
+  metadata: {},
+  targets: ['sqlite'],
+});
+```
+
+## Pattern 4: With Knowledge Graph
+
+```typescript
+import { Memory, createGraphStore } from '@pyx-memory/core';
+import type { StoreTarget, IngestEntity, IngestRelationship } from '@pyx-memory/shared';
+
+// 1. Create and initialize graph store BEFORE Memory
+const graphStore = createGraphStore({}); // returns SQLiteGraphStore (default)
+await graphStore.initialize({});         // REQUIRED — Memory does NOT init this for you
+
+// For Neo4j instead: createGraphStore({ neo4jUrl: 'bolt://localhost:7687' })
+
+const memory = new Memory({
+  dataDir: './data',
+  graphStore, // enables graph RAG search
+});
+await memory.initialize();
+
+// Graph storage is agent-driven — YOU provide entities and relationships explicitly
+await memory.store({
+  content: 'Alice works at Acme Corp as a senior engineer',
+  type: 'long-term',
+  metadata: {},
+  targets: ['sqlite', 'vector', 'graph'],
+  entities: [
+    { name: 'Alice', type: 'PERSON', properties: { role: 'senior engineer' } },
+    { name: 'Acme Corp', type: 'ORGANIZATION' },
+  ],
+  relationships: [
+    { source: 'Alice', target: 'Acme Corp', type: 'WORKS_AT' },
+  ],
+});
+
+// Graph-aware search
+const results = await memory.search({ query: 'Alice employer', strategy: 'graph' });
+
+// Cleanup both
+await memory.shutdown();
+await graphStore.shutdown();
+```
+
+## Pattern 5: With LLM Lifecycle
+
+```typescript
+import { Memory } from '@pyx-memory/core';
+import type { LLMCallback } from '@pyx-memory/core';
+
+// LLMCallback: any function that takes a prompt string and returns a completion string
+const llm: LLMCallback = async (prompt) => {
+  const res = await fetch('https://api.anthropic.com/v1/messages', {
+    method: 'POST',
+    headers: {
+      'x-api-key': process.env.ANTHROPIC_API_KEY!,
+      'content-type': 'application/json',
+      'anthropic-version': '2023-06-01',
+    },
+    body: JSON.stringify({
+      model: 'claude-sonnet-4-20250514',
+      max_tokens: 1024,
+      messages: [{ role: 'user', content: prompt }],
+    }),
+  });
+  const data = await res.json() as any;
+  return data.content[0].text;
+};
+
+const memory = new Memory({
+  dataDir: './data',
+  llm, // enables LLM-powered lifecycle
+});
+await memory.initialize();
+
+// Now lifecycle methods use LLM intelligence
+await memory.consolidate();                    // LLM scoring + dedup + conflict resolution
+await memory.summarizeSession('session-123');   // LLM summarization
+await memory.runDecay();                        // importance-based archival
+```
+
+**Without LLM**: Lifecycle still works using heuristic fallbacks (regex extraction, embedding-distance dedup, formula-based scoring). LLM makes it smarter, not mandatory.
+
+## Pattern 6: File Ingestion
+
+```typescript
+import { IngestionAgent, Memory } from '@pyx-memory/core';
+
+const memory = new Memory({ dataDir: './data' });
+await memory.initialize();
+
+const agent = new IngestionAgent({
+  llm: myLlmCallback,                          // optional: smart classification + enrichment
+  embedder: (texts) => myEmbedder.embed(texts), // optional: semantic chunking (separate from Memory's internal embedder)
+  useSemanticChunking: true,
+  useStructuralChunking: false,
+  enableEnrichment: true,
+  enableMetadata: true,
+  enableHierarchical: false,                    // requires LLM
+});
+
+// Supported: .txt, .md, .csv, .pdf, .docx, .json, .html
+const buffer = Buffer.from(await Bun.file('report.pdf').arrayBuffer());
+const result = await agent.ingest(buffer, 'report.pdf', memory);
+// result: { filename, fileType, chunks, entryIds, totalCharacters }
+```
+
+**Note**: `IngestionAgent` may accept its own `embedder` for semantic chunking. This is separate from Memory's internal embedding — Memory handles its own embedding automatically.
+
+## Pattern 7: Factory with Auto-Mode Switching
+
+```typescript
+import { createMemory } from '@pyx-memory/core';
+
+// Embedded mode (default)
+const memory = createMemory({
+  dataDir: './data',
+});
+
+// Sidecar mode (when MEMORY_URL is set)
+const remote = createMemory({
+  memoryUrl: process.env.MEMORY_URL, // e.g., 'http://localhost:7822'
+  apiKey: process.env.MEMORY_API_KEY,
+});
+
+await memory.initialize();
+
+// WARNING: createMemory() returns MemoryInterface, NOT ExtendedMemoryInterface.
+// If you need lifecycle methods, cast:
+// const extended = memory as ExtendedMemoryInterface;
+// Or prefer `new Memory()` / `new MemoryClient()` directly.
+```
+
+---
+
+## Adding as Git Submodule (Recommended for Embedded Mode)
+
+```bash
+git submodule add https://github.com/fysoul17/pyx-memory-v1.git vendor/pyx-memory
+```
+
+Add to your `package.json` workspaces:
+
+```json
+{
+  "workspaces": [
+    "packages/*",
+    "vendor/pyx-memory/packages/shared",
+    "vendor/pyx-memory/packages/client",
+    "vendor/pyx-memory/packages/core"
+  ]
+}
+```
+
+Then: `bun install`
+
+---
+
+## MemoryOptions Quick Reference
+
+`embedder` has been removed from MemoryOptions. Memory internally creates a `LocalEmbeddingProvider` using BGE-M3 (1024 dimensions) via `@huggingface/transformers`. You never need to provide an embedding function.
+
+See [reference/types.md](../reference/types.md#memoryoptions-reference) for the full MemoryOptions table.