@pyxmate/memory 0.2.7-beta → 0.2.10-beta

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyxmate/memory",
-  "version": "0.2.7-beta",
+  "version": "0.2.10-beta",
   "type": "module",
   "description": "SDK for pyx-memory — Memory as a Service for AI agents",
   "license": "MIT",
@@ -44,8 +44,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "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",
+    "build": "tsup",
     "typecheck": "tsc --noEmit",
     "clean": "rm -rf dist skills node_modules .turbo"
   },

package/skills/pyx-memory/SKILL.md

@@ -40,6 +40,8 @@ curl -s -X POST {{ENDPOINT}}/api/memory/ingest \
   -d '{"content":"WHAT_HAPPENED","type":"long-term","metadata":{"source":"agent","topic":"TOPIC","project":"PROJECT_NAME"}}'
 ```
 
+When the memory mentions specific people, tools, organizations, or other named subjects, also include `entities` and `relationships` to populate the knowledge graph. See [reference/http-api.md](reference/http-api.md) for entity types, relationship types, and examples.
+
 ## Search: before making assumptions
 
 Search for relevant context in these situations:
@@ -60,6 +62,7 @@ curl -s "{{ENDPOINT}}/api/memory/search?q=QUERY&limit=5" \
 - Keep content factual and concise — decisions, not deliberation
 - Do NOT store ephemeral info (file contents, current state, in-progress work)
 - One memory per concept — don't bundle unrelated things
+- Extract entities when content mentions specific people, tools, technologies, organizations, locations, or events by name
 
 ---
 

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

@@ -10,6 +10,18 @@ await memory.store({
   metadata: { source: 'settings' },
 });
 
+// Store with entities — populates the knowledge graph
+await memory.store({
+  content: 'Alice switched the project to TypeScript for type safety',
+  type: 'long-term',
+  metadata: { source: 'decisions' },
+  entities: [
+    { name: 'Alice', type: 'PERSON' },
+    { name: 'TypeScript', type: 'TOOL' },
+  ],
+  relationships: [{ source: 'Alice', target: 'TypeScript', type: 'USES' }],
+});
+
 // Store with explicit targets (e.g., sqlite only)
 await memory.store({
   content: 'Temporary working note',

package/skills/pyx-memory/reference/http-api.md

@@ -54,6 +54,47 @@ const client = new MemoryClient('http://localhost:7822', process.env.MEMORY_API_
 | GET | `/api/memory/query-as-of?asOf=...` | Bi-temporal point-in-time query (asOf, type, agentId, source, limit) |
 | GET | `/api/memory/query-by-event-time?startTime=...&endTime=...` | Bi-temporal event time range query (startTime, endTime, type, agentId, source, limit) |
 
+## Entity Extraction (Knowledge Graph)
+
+When storing memories that mention named subjects, include `entities` and `relationships` in the ingest request to populate the knowledge graph. This enables graph-based RAG and dashboard visualization.
+
+### Entity types
+
+`PERSON`, `ORGANIZATION`, `CONCEPT`, `TOOL`, `LOCATION`, `EVENT`
+
+### Relationship types
+
+`USES`, `OWNS`, `DEPENDS_ON`, `RELATED_TO`, `CREATED_BY`, `PART_OF`, `IS_A`, `WORKS_AT`, `LOCATED_IN`
+
+### Example: store with entities
+
+```bash
+curl -s -X POST {{ENDPOINT}}/api/memory/ingest \
+  -H "Authorization: Bearer {{API_KEY}}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "content":"Alice switched the frontend from JavaScript to TypeScript for type safety",
+    "type":"long-term",
+    "metadata":{"source":"agent","topic":"tech-stack","project":"my-project"},
+    "entities":[
+      {"name":"Alice","type":"PERSON"},
+      {"name":"TypeScript","type":"TOOL"},
+      {"name":"JavaScript","type":"TOOL"}
+    ],
+    "relationships":[
+      {"from":"Alice","to":"TypeScript","type":"USES"},
+      {"from":"TypeScript","to":"JavaScript","type":"RELATED_TO"}
+    ]
+  }'
+```
+
+**When to extract**: Always extract when content mentions specific people, tools, technologies, organizations, locations, or events by name. Skip only for abstract observations with no named subjects (e.g., "prefer tabs over spaces").
+
+**Entity fields**: `name` (required), `type` (required), `metadata` (optional properties object)
+**Relationship fields**: `from` (source entity name), `to` (target entity name), `type` (required)
+
+---
+
 ## Response Format
 
 All responses follow: `{ success: boolean, data?: T, error?: string }`

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

@@ -1,266 +0,0 @@
----
-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; or sqlite + vector + graph when graphStore configured)
-// When graphStore is configured, graph is auto-included in defaults.
-// If no entities provided, graph is silently skipped.
-await memory.store({
-  content: 'User prefers dark mode',
-  type: 'long-term',
-  metadata: { source: 'settings' },
-});
-
-// Store with entities — graph is populated automatically when graphStore configured
-await memory.store({
-  content: 'Alice works at Acme Corp',
-  type: 'long-term',
-  metadata: {},
-  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` to populate the graph — graph is auto-included in defaults when graphStore is configured, but silently skipped if no entities are provided
-- **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 a configured `graphStore` — throws MemoryError (but graph without entities is fine — silently skipped)
-- **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

@@ -1,53 +0,0 @@
-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

@@ -1,25 +0,0 @@
-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

@@ -1,14 +0,0 @@
-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

@@ -1,103 +0,0 @@
-# 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

@@ -1,223 +0,0 @@
-# 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.

package/skills/pyx-memory-integration/reference/advanced.md

@@ -1,139 +0,0 @@
-# Advanced Features
-
-## RAG Strategies
-
-| Strategy | How It Works | Requirements |
-|----------|-------------|--------------|
-| `'naive'` | Embed query → vector similarity → top-K | (default, always available) |
-| `'graph'` | Extract entities → graph traversal → context expansion | `graphStore` in MemoryOptions |
-| `'hybrid'` | BM25 + vector + graph + community summaries → RRF fusion (k=60) → reranking | `graphStore` in MemoryOptions |
-| `'agentic'` | LLM decides strategy → iterative refinement (3 rounds) | `reasoningProvider` in MemoryOptions |
-
-```typescript
-// Naive (default)
-await memory.search({ query: 'user preferences', limit: 10 });
-
-// Graph
-await memory.search({ query: 'who works at Acme', strategy: 'graph', limit: 10 });
-
-// Hybrid (recommended for best quality)
-await memory.search({ query: 'deployment config', strategy: 'hybrid', limit: 10 });
-
-// With query transformation (HyDE generates hypothetical answer, embeds that instead)
-// EMBEDDED ONLY — enableHyDE not forwarded by HTTP API
-await memory.search({ query: 'deployment config', strategy: 'hybrid', enableHyDE: true });
-
-// With reranking (cross-encoder scores each result for precision)
-// EMBEDDED ONLY — enableRerank not forwarded by HTTP API
-await memory.search({ query: 'deployment config', strategy: 'hybrid', enableRerank: true });
-```
-
-### Retrieval Pipeline (Hybrid Strategy)
-
-```
-Query → Stage 0: Transform (decompose, HyDE, multi-query)
-      → Stage 1: Parallel retrieval (BM25/FTS5 + dense vector + graph traverse + community summaries)
-      → Stage 2: RRF fusion (k=60) + dedup
-      → Stage 3: Cross-encoder reranking → top-N
-```
-
----
-
-## Bi-Temporal Model
-
-Every entry tracks two timestamps for temporal reasoning:
-
-- **`eventTime`**: When the fact/event actually occurred
-- **`ingestTime`**: When it was stored in memory (auto-set)
-
-**Sidecar note**: All `StoreInput` fields (including `eventTime`, `id`, `parentId`, `ingestTime`) are forwarded by `MemoryClient.store()`. Temporal search filters (`eventTimeRange`, `asOf`) are forwarded by `MemoryClient.search()`. However, `filters` (source, importanceMin, parentId, contentType), `enableHyDE`, and `enableRerank` are still not forwarded by the search endpoint.
-
-```typescript
-// Store with explicit event time (works in both embedded and sidecar)
-await memory.store({
-  content: 'User changed address to 123 Main St',
-  type: 'long-term',
-  metadata: {},
-  eventTime: '2026-01-15T00:00:00Z',  // when it happened
-});
-
-// Query as-of (available via MemoryClient.queryAsOf() or HTTP endpoint)
-const snapshot = await memory.queryAsOf('2026-01-20T00:00:00Z', { type: 'long-term' });
-
-// Query by event time range (available via MemoryClient.queryByEventTime() or HTTP endpoint)
-const events = await memory.queryByEventTime('2026-01-01T00:00:00Z', '2026-02-01T00:00:00Z');
-
-// Filter by event time range in search (EMBEDDED ONLY via filters param)
-await memory.search({
-  query: 'address',
-  filters: { eventTimeRange: ['2026-01-01', '2026-02-01'] },
-});
-```
-
----
-
-## Consolidation Pipeline
-
-When `consolidate()` runs, it executes a 7-step pipeline:
-
-1. **Extract facts** — LLM or regex extraction of factual statements
-2. **Deduplicate** — Content hash + vector similarity (>0.90) → LLM classifies ADD/UPDATE/DELETE/NOOP
-3. **Resolve conflicts** — Detect contradictions, resolve by recency and source trust
-4. **Score importance** — LLM rates 1-10 (or heuristic: recency + access count + entity density)
-5. **Enrich graph** — Extract entities and relationships, merge with existing graph
-6. **Summarize** — Rolling session summaries, memory compaction
-7. **Decay** — Archive entries below importance threshold: `importance * 0.995^hours * (1 + 0.02 * min(accessCount, 20)) * eventAgeFactor`
-
-All steps have **non-LLM fallbacks** — consolidation works without an LLM, just less intelligently.
-
----
-
-## Community Detection
-
-When a `graphStore` is configured, the system can detect communities of related entities using the Louvain algorithm:
-
-```typescript
-import { CommunityDetector } from '@pyx-memory/core';
-
-const detector = new CommunityDetector(graphStore, llm);
-const communities = await detector.detect();
-// Each community: { id, nodeIds, summary? }
-// Summaries are used by hybrid RAG for corpus-level queries
-```
-
-Communities are leveraged by the hybrid RAG strategy to answer broad "what are the themes" queries.
-
----
-
-## Automatic Behaviors
-
-These happen automatically — no configuration needed:
-
-- **PII detection**: Every `store()` scans content and sets `metadata.piiDetected` + `metadata.piiTypes` if found
-- **Content hashing**: Every `store()` computes SHA-256 `contentHash`
-- **Access tracking**: Every `search()` increments `accessCount` and updates `lastAccessed` on returned entries
-- **FTS5 sync**: SQLite triggers keep full-text search index in sync with memory_entries
-- **Graph storage**: When `targets` includes `'graph'`, agent-provided `entities` are stored to the graph (best-effort — failures don't block store)
-- **Auto-registration on import**: Importing `@pyx-memory/core` registers StubEmbeddingProvider, LanceDBProvider, and NaiveRAGEngine
-- **Graph/Agentic RAG registration**: Memory constructor auto-registers GraphRAGEngine and AgenticRAGEngine when you pass `graphStore` or `reasoningProvider`
-- **Agent scoping**: If `agentId` is set in MemoryOptions, all operations auto-filter by that agent
-
----
-
-## Initialization Sequence
-
-```
-1. (Optional) Create and await graphStore.initialize()
-2. Construct: new Memory({ graphStore?, llm?, ... })   ← embedding is internal (BGE-M3)
-3. Await: memory.initialize()    ← creates SQLite DB + LanceDB vector store
-4. Use: store(), search(), etc.
-5. Cleanup: await memory.shutdown()
-6. (Optional) await graphStore.shutdown()
-```
-
-**Memory.initialize()** creates:
-- SQLite database at `{dataDir}/memory/memory.db` (with FTS5 + migrations)
-- LanceDB vector store at `{dataDir}/vectors/`
-- Both directories are created automatically (mkdirSync recursive)
-
-**Memory does NOT** call `graphStore.initialize()` — you must do this yourself before or after constructing Memory, but before calling `memory.initialize()`.

package/skills/pyx-memory-integration/reference/http-api.md

@@ -1,82 +0,0 @@
-# pyx-memory HTTP API Reference
-
-## Authentication
-
-When the server has `API_KEY` configured, all requests (except `/health`) require one of:
-
-```
-Authorization: Bearer <your-api-key>
-X-API-Key: <your-api-key>
-```
-
-Destructive operations (DELETE, forget, decay, consolidate, reindex) require `ADMIN_API_KEY` when configured (falls back to `API_KEY`).
-
-`MemoryClient` handles this automatically when `apiKey` is passed to the constructor:
-```typescript
-const client = new MemoryClient('http://localhost:7822', process.env.MEMORY_API_KEY);
-```
-
-## Core (10 endpoints)
-
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| GET | `/health` | Public health check (status only — no internals exposed) |
-| GET | `/admin/health` | Admin health check (version, uptime, embedding provider, memory stats) |
-| POST | `/api/memory/ingest` | Store a memory (JSON: `{ content, type, metadata, agentId?, sessionId?, targets?, entities?, relationships?, importance?, source?, eventTime?, id?, parentId?, ingestTime? }`) |
-| POST | `/api/memory/ingest/file` | Upload file (multipart, 50MB limit) |
-| GET | `/api/memory/search?query=...&strategy=...&limit=...` | Search memories — **does NOT support** filters, enableHyDE, enableRerank |
-| GET | `/api/memory/stats` | Memory statistics |
-| GET | `/api/memory/entries?page=...&limit=...` | List entries (paginated) |
-| GET | `/api/memory/entries/:id` | Get entry by ID |
-| DELETE | `/api/memory/entries/:id` | Delete entry |
-| DELETE | `/api/memory/sessions/:sessionId` | Clear session |
-
-## Graph (4 endpoints)
-
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| GET | `/api/memory/graph/nodes?name=...&type=...` | Find graph nodes |
-| GET | `/api/memory/graph/edges` | Graph stats |
-| GET | `/api/memory/graph/relationships` | List relationships |
-| POST | `/api/memory/graph/query` | Traverse (JSON: `{ nodeId, depth? }`) |
-
-## Lifecycle (9 endpoints)
-
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| POST | `/api/memory/consolidate` | Run consolidation pipeline |
-| POST | `/api/memory/forget/:id` | Soft-delete (JSON: `{ reason? }`) |
-| POST | `/api/memory/sessions/:sid/summarize` | Summarize session |
-| POST | `/api/memory/decay` | Run decay pass |
-| POST | `/api/memory/reindex` | Rebuild FTS5 + vector indices |
-| DELETE | `/api/memory/source/:source` | Delete by source |
-| GET | `/api/memory/consolidation-log` | Audit trail |
-| GET | `/api/memory/query-as-of?asOf=...` | Bi-temporal point-in-time query (asOf, type, agentId, source, limit) |
-| GET | `/api/memory/query-by-event-time?startTime=...&endTime=...` | Bi-temporal event time range query (startTime, endTime, type, agentId, source, limit) |
-
-## Response Format
-
-All responses follow: `{ success: boolean, data?: T, error?: string }`
-
----
-
-## Server Environment Variables
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `MEMORY_SERVER_PORT` | `7822` | HTTP server port |
-| `DATA_DIR` | `./data` | Storage directory |
-| ~~`EMBEDDING_PROVIDER`~~ | — | **Removed** — embedding is now internal (BGE-M3 via LocalEmbeddingProvider) |
-| ~~`EMBEDDING_API_KEY`~~ | — | **Removed** — no external embedding provider needed |
-| ~~`EMBEDDING_MODEL`~~ | — | **Removed** — model is always BGE-M3 (ONNX int8 quantized) |
-| `EMBEDDING_DIMENSIONS` | `1024` | Dimension override for the internal LocalEmbeddingProvider (default: 1024) |
-| `NEO4J_URL` | — | Neo4j bolt URL (enables Neo4j graph store) |
-| `NEO4J_USERNAME` | `neo4j` | Neo4j username |
-| `NEO4J_PASSWORD` | — | Neo4j password (never logged) |
-| `API_KEY` | — | API key for authenticating requests. Unset = open access |
-| `ADMIN_API_KEY` | — | Separate admin key for destructive ops (DELETE, forget, decay, consolidate, reindex). Falls back to `API_KEY` |
-| `CORS_ORIGIN` | `*` | CORS allowed origin. Set to specific domain in production |
-| `MAX_REQUEST_BODY_MB` | `10` | Maximum request body size in MB |
-| `NODE_ENV` | `development` | Set to `production` to mask 5xx error details and enable HSTS |
-| `PII_POLICY` | `flag` | PII handling: `flag` (detect + tag), `redact` (replace with [REDACTED]), `block` (reject 400) |
-| `RATE_LIMIT_RPM` | `0` | Requests per minute per IP. 0 = disabled |

package/skills/pyx-memory-integration/reference/parity.md

@@ -1,63 +0,0 @@
-# Feature Parity: Embedded vs Sidecar
-
-**Most features are available in both modes.** The HTTP API and MemoryClient forward all core `StoreInput` fields. A few advanced search parameters remain embedded-only.
-
-## store() Field Parity
-
-| Field | Embedded `Memory.store()` | Sidecar `MemoryClient.store()` |
-|-------|--------------------------|-------------------------------|
-| content | yes | yes |
-| type | yes | yes |
-| metadata | yes | yes |
-| agentId | yes | yes |
-| sessionId | yes | yes |
-| targets | yes | yes |
-| entities | yes | yes |
-| relationships | yes | yes |
-| importance | yes | yes |
-| source | yes | yes |
-| eventTime | yes | yes |
-| id (custom) | yes | yes |
-| parentId | yes | yes |
-| ingestTime | yes | yes |
-
-**All StoreInput fields are forwarded.** Full parity.
-
-## search() Param Parity
-
-| Param | Embedded `Memory.search()` | Sidecar `MemoryClient.search()` |
-|-------|---------------------------|--------------------------------|
-| query, limit, type, agentId, strategy | yes | yes |
-| eventTimeRange (bi-temporal search) | yes | yes |
-| asOf (point-in-time search) | yes | yes |
-| **filters** (source, importanceMin, parentId, contentType) | yes | **NO** — not forwarded |
-| **enableHyDE** | yes | **NO** — not forwarded |
-| **enableRerank** | yes | **NO** — not forwarded |
-
-**Impact**: Sidecar consumers cannot use advanced search filters, HyDE query expansion, or reranking. Temporal search filters (eventTimeRange, asOf) ARE supported.
-
-## Endpoint Coverage by Client
-
-| Server Endpoint | MemoryClient | DashboardClient |
-|----------------|-------------|-----------------|
-| All core (9) | yes | yes (inherited) |
-| Graph nodes/edges/query (3) | yes (concrete methods) | yes (inherited) |
-| **Graph relationships** | **NO** | yes (`graphRelationships()`) |
-| All lifecycle (7) | yes | yes (inherited) |
-| **Consolidation log** | **NO** | yes (`consolidationLog()`) |
-| Query as-of (bi-temporal) | yes (`queryAsOf()`) | yes (inherited) |
-| Query by event time | yes (`queryByEventTime()`) | yes (inherited) |
-
-## Security Features (Server-side)
-
-| Feature | Configuration |
-|---------|--------------|
-| API key auth | `API_KEY` env var (unset = open access) |
-| Admin key for destructive ops | `ADMIN_API_KEY` env var |
-| Rate limiting | `RATE_LIMIT_RPM` env var (0 = disabled) |
-| CORS | `CORS_ORIGIN` env var (default: `*`) |
-| Security headers | Always on (CSP, X-Frame-Options, nosniff) |
-| HSTS | Auto-enabled when `NODE_ENV=production` |
-| PII policy | `PII_POLICY` env var (`flag` / `redact` / `block`) |
-| Body size limit | `MAX_REQUEST_BODY_MB` env var (default: 10) |
-| Error masking | 5xx details hidden when `NODE_ENV=production` |

package/skills/pyx-memory-integration/reference/types.md

@@ -1,203 +0,0 @@
-# pyx-memory Type Reference
-
-## Contents
-- Type Cheat Sheet
-- MemoryInterface (9 methods)
-- ExtendedMemoryInterface (6 lifecycle methods)
-- MemoryClient Constructor and Concrete Methods
-- DashboardClient
-- MemorySearchResult, MemoryEntry, MemorySearchParams
-- MemoryOptions Reference
-- Embedding Dimension Defaults
-
-## Type Cheat Sheet
-
-| Type | Signature | Import From |
-|------|-----------|-------------|
-| `LLMCallback` | `(prompt: string) => Promise<string>` | `@pyx-memory/core` |
-| `ReasoningProvider` | `(prompt: string) => Promise<string>` | `@pyx-memory/core` |
-| `StoreInput` | `Omit<MemoryEntry, 'id' \| 'createdAt'> & { targets?, entities?, relationships? }` | `@pyx-memory/core` |
-| `MemoryType` | `'short-term' \| 'long-term' \| 'working' \| 'episodic' \| 'summary'` | `@pyx-memory/shared` |
-| `RAGStrategy` | `'naive' \| 'graph' \| 'agentic' \| 'hybrid'` | `@pyx-memory/shared` |
-| `VectorProvider` | `'lancedb'` | `@pyx-memory/shared` |
-| `StoreTarget` | `'sqlite' \| 'vector' \| 'graph'` | `@pyx-memory/shared` |
-| `IngestEntity` | `{ name, type, properties? }` | `@pyx-memory/shared` |
-| `IngestRelationship` | `{ source, target, type, properties? }` | `@pyx-memory/shared` |
-| `EntityType` | `'PERSON' \| 'ORGANIZATION' \| 'CONCEPT' \| 'TOOL' \| 'LOCATION' \| 'EVENT'` | `@pyx-memory/core` |
-| `RelationType` | `'USES' \| 'OWNS' \| 'DEPENDS_ON' \| 'RELATED_TO' \| 'CREATED_BY' \| 'PART_OF' \| 'IS_A' \| 'WORKS_AT' \| 'LOCATED_IN'` | `@pyx-memory/core` |
-| `MemoryListParams` | `{ page?, limit?, type?, agentId? }` | `@pyx-memory/client` |
-| `MemoryListResult` | `{ entries, totalCount, page, limit }` | `@pyx-memory/client` |
-| `IngestionResult` | `{ filename, chunks, totalCharacters }` | `@pyx-memory/client` |
-| `MemoryServerError` | `Error` with `.status` and `.isNotFound` | `@pyx-memory/client` |
-| `GraphNode` | `{ id, name, type, properties, memoryEntryIds }` | `@pyx-memory/shared` |
-| `GraphTraversalResult` | `{ nodes, relationships, paths }` | `@pyx-memory/shared` |
-
----
-
-## MemoryInterface (9 methods)
-
-```typescript
-interface MemoryInterface {
-  initialize(): Promise<void>;
-  store(entry: Omit<MemoryEntry, 'id' | 'createdAt'> & { id?: string; createdAt?: string; targets?: StoreTarget[]; entities?: IngestEntity[]; relationships?: IngestRelationship[] }): Promise<MemoryEntry>;
-  search(params: MemorySearchParams): Promise<MemorySearchResult>;
-  list(params?: MemoryListParams): Promise<MemoryListResult>;  // paginated entry listing
-  get(id: string): Promise<MemoryEntry | null>;
-  delete(id: string): Promise<boolean>;
-  clearSession(sessionId: string): Promise<number>;
-  stats(): Promise<MemoryStats>;
-  shutdown(): Promise<void>;
-}
-```
-
-## ExtendedMemoryInterface (adds 6 lifecycle methods)
-
-```typescript
-interface ExtendedMemoryInterface extends MemoryInterface {
-  consolidate(): Promise<ConsolidationRunResult>;
-  forget(id: string, reason?: string): Promise<boolean>;
-  summarizeSession(sessionId: string): Promise<MemoryEntry | null>;
-  runDecay(): Promise<number>;
-  reindex(): Promise<void>;
-  deleteBySource(source: string): Promise<number>;
-}
-```
-
-## MemoryClient Constructor and Concrete Methods
-
-```typescript
-// Constructor: URL required, apiKey optional
-const client = new MemoryClient('http://localhost:7822');                    // no auth
-const client = new MemoryClient('http://localhost:7822', 'my-api-key');     // with auth
-const client = new MemoryClient('http://localhost:7822', process.env.MEMORY_API_KEY); // from env
-```
-
-When `apiKey` is provided, all requests include `Authorization: Bearer <key>`. Empty or whitespace-only keys are ignored.
-
-`MemoryClient` implements `ExtendedMemoryInterface` AND has additional methods not on any interface.
-Graph queries and file ingestion are available without `@pyx-memory/core`.
-
-```typescript
-class MemoryClient implements ExtendedMemoryInterface {
-  // ... all 15 interface methods (9 base + 6 lifecycle) ...
-
-  // Graph operations (call pyx-memory server's graph endpoints)
-  graphNodes(): Promise<GraphNode[]>;
-  graphEdges(): Promise<{ stats: { nodeCount: number; edgeCount: number } }>;
-  graphQuery(query: { nodeId: string; depth?: number }): Promise<GraphTraversalResult>;
-
-  // File ingestion (multipart upload to server)
-  ingestFile(file: File): Promise<IngestionResult>;
-
-  // Bi-temporal queries
-  queryAsOf(asOf: string, filters?: TemporalQueryFilters): Promise<MemoryEntry[]>;
-  queryByEventTime(startTime: string, endTime: string, filters?: TemporalQueryFilters): Promise<MemoryEntry[]>;
-}
-```
-
-**Key insight for consumers**: You do NOT need `@pyx-memory/core` for graph queries or file ingestion.
-`MemoryClient` already proxies these through the HTTP API.
-
-## DashboardClient (extends MemoryClient)
-
-`DashboardClient` from `@pyx-memory/dashboard` adds dashboard-specific methods:
-
-```typescript
-import { DashboardClient } from '@pyx-memory/dashboard';
-
-class DashboardClient extends MemoryClient {
-  consolidationLog(limit?: number): Promise<ConsolidationLogEntry[]>;
-  graphRelationships(limit?: number): Promise<{ relationships: GraphRelationship[]; totalCount: number }>;
-  graphFull(limit?: number): Promise<{ nodes: GraphNode[]; relationships: GraphRelationship[] }>;
-  listEntriesPaginated(filters?: EntryFilters): Promise<PaginatedEntries>;
-  fetchHealthRaw(): Promise<RawHealthResponse>;
-}
-```
-
-The dashboard package also provides: `Poller` (auto-polling), `computeMetrics()`, `computeTypeDistribution()`,
-`enrichHealth()`, `transformGraphData()`, `toD3ForceFormat()`, `toGraphologyFormat()`, and React hooks
-(`useMemoryStats`, `useMemoryEntries`, `useKnowledgeGraph`, `useConsolidationLog`, `useMemoryHealth`, `useTypeDistribution`).
-
-## MemorySearchResult
-
-```typescript
-interface MemorySearchResult {
-  entries: MemoryEntry[];
-  totalCount: number;
-  strategy: RAGStrategy;
-  scoredEntries?: Array<{ entry: MemoryEntry; score: number }>;  // ranked results with relevance scores
-}
-```
-
-## MemoryEntry (full shape)
-
-```typescript
-interface MemoryEntry {
-  id: string;
-  content: string;
-  type: MemoryType;
-  agentId?: string;
-  sessionId?: string;
-  metadata: Record<string, unknown>;
-  embedding?: number[];         // @deprecated — managed internally by vector store
-  createdAt: string;           // ISO 8601
-  contentHash?: string;        // SHA-256
-  importance?: number;         // 1-10
-  accessCount?: number;
-  lastAccessed?: string;       // ISO 8601
-  parentId?: string;           // hierarchical storage
-  source?: string;             // filename, URL, session ID
-  eventTime?: string;          // when event happened (bi-temporal)
-  ingestTime?: string;         // when stored (bi-temporal)
-}
-```
-
-## MemorySearchParams + SearchFilters
-
-```typescript
-interface MemorySearchParams {
-  query: string;
-  type?: MemoryType;
-  agentId?: string;
-  limit?: number;               // default varies by engine
-  strategy?: RAGStrategy;       // default: 'naive'
-  filters?: SearchFilters;
-  enableHyDE?: boolean;         // Hypothetical Document Embedding for query expansion
-  enableRerank?: boolean;       // Cross-encoder reranking of results
-}
-
-interface SearchFilters {
-  source?: string;
-  importanceMin?: number;
-  eventTimeRange?: [string, string];  // [start, end] ISO timestamps
-  parentId?: string;
-  contentType?: string;
-}
-```
-
-## MemoryOptions Reference
-
-> **Embedding is internal** — pyx-memory uses `LocalEmbeddingProvider` with BGE-M3 (1024d) automatically. You do NOT pass an `embedder` option.
-
-| Field | Type | Required | Default | Notes |
-|-------|------|----------|---------|-------|
-| `dataDir` | `string` | no | `'./data'` | Use `':memory:'` for tests (LanceDB still writes to `/tmp`) |
-| `vectorProvider` | `VectorProvider` | no | `'lancedb'` | |
-| `dimensions` | `number` | no | `1024` | Default: 1024 (matches internal BGE-M3 model) |
-| `graphStore` | `GraphStore` | no | `undefined` | Enables graph target in store routing |
-| `reasoningProvider` | `ReasoningProvider` | no | `undefined` | Enables agentic RAG |
-| `llm` | `LLMCallback` | no | `undefined` | Enables LLM-powered lifecycle (consolidation, summarization, scoring) |
-| `skipDuplicates` | `boolean` | no | `false` | Content-hash dedup on store |
-| `agentId` | `string` | no | `undefined` | Auto-scopes ALL store/search/stats/decay operations to this agent |
-| `qdrantUrl` | `string` | no | `undefined` | @deprecated — Qdrant support is vestigial |
-
-## Embedding Dimension Defaults by Provider
-
-> **Memory always uses `LocalEmbeddingProvider` internally.** The other providers are available for standalone use but are not used by the `Memory` class.
-
-| Provider | Default Dimensions | Model |
-|----------|-------------------|-------|
-| `StubEmbeddingProvider` | 1024 | hash-based (testing only) |
-| `OpenAIEmbeddingProvider` | 1536 | text-embedding-3-small |
-| `AnthropicEmbeddingProvider` | 1024 | voyage-3 (Voyage AI) |
-| `LocalEmbeddingProvider` | 1024 | BGE-M3 (ONNX int8 quantized) |