@pyxmate/memory 0.20.5 → 0.21.2

package/skills/pyx-memory/reference/sdk-guide.md

@@ -1,233 +0,0 @@
-# pyx-memory SDK Integration Guide
-
-Reference for integrating pyx-memory into TypeScript/Bun projects.
-Runtime requirement: **Bun v1.2+** (not Node.js). Uses `bun:sqlite` natively.
-
-## Quick Decision Tree
-
-```
-Building pyx-memory itself or its server?
-  → Embedded mode: import { Memory } from '@pyx-memory/core'
-
-Consuming pyx-memory from another project?
-  → 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';
-
-const memory = new Memory({ dataDir: './data' });
-await memory.initialize(); // REQUIRED — throws if you skip this
-
-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' }],
-});
-
-const results = await memory.search({ query: 'user preferences', limit: 5 });
-
-await memory.shutdown(); // REQUIRED — releases SQLite + LanceDB resources
-```
-
-## Minimal Working Example (Sidecar / HTTP)
-
-```typescript
-import { MemoryClient } from '@pyx-memory/client';
-
-const memory = new MemoryClient('http://localhost:7822');
-
-// With auth (production)
-const authedMemory = new MemoryClient('http://localhost:7822', process.env.MEMORY_API_KEY);
-
-// With auth + multi-tenant headers (production, multi-tenant mode)
-const tenantMemory = new MemoryClient('http://localhost:7822', {
-  apiKey: process.env.MEMORY_API_KEY,
-  defaultHeaders: {
-    'X-Tenant-Id': 'tenant-abc',
-    'X-User-Id': 'user-123',
-  },
-});
-
-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 (25 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`
-
-## 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
-- **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** implement `DisabledMemory` (no-op) for graceful degradation when memory is unavailable
-- **DO** set `tenantId` on `MemoryOptions` or pass `X-Tenant-Id` header for multi-tenant deployments
-- **DO** use `MemoryClientOptions` with `defaultHeaders` for tenant/access-level headers in sidecar mode
-
-### DON'T
-
-- **DON'T** assume `createMemory()` returns `ExtendedMemoryInterface` — it returns `MemoryInterface`
-- **DON'T** use `targets: ['graph']` without a configured `graphStore` — throws MemoryError
-- **DON'T** use `strategy: 'graph'` without passing `graphStore`
-- **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
-- **DON'T** run `TENANT_MODE=multi` without `API_KEY` — multi-tenant without auth is dangerous
-- **DON'T** import `@pyx-memory/core` in consumer projects — use `@pyx-memory/client`
-- **DON'T** expect `filters`, `enableHyDE`, or `enableRerank` to work in sidecar mode
-
-## Post-Integration Checklist
-
-```bash
-bun .claude/skills/pyx-memory/scripts/diagnose-integration.ts --json
-```
-
-Interpret `verdict`: `"healthy"` = done, otherwise fix each `criticalIssues` entry and re-run.
-
-**Common failure: DisabledMemory (no-op)**
-If `MEMORY_URL` is not set, the client silently falls back to a no-op implementation. The diagnostic tool detects this via checks S5 and I1.
-
-## 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`.
-
-## Two-Phase PDF Enrichment
-
-When ingesting PDFs that contain images, `ingestFileEvents()` runs a three-phase enrichment flow via `EnrichmentCallbacks`. The SDK handles all phases automatically and emits typed `IngestEvent`s as it goes:
-
-1. **Server upload** — text extracted and stored immediately; server emits `progress` events with stage `parsing` then `storing`
-2. **Image description** — each extracted image is fetched and described via your LLM vision callback (batched, 5 concurrent); SDK emits `progress`/`heartbeat` events with stage `enrichment`
-3. **Enrichment write** — descriptions + entities POSTed back to the server's `/enrich` endpoint; SDK emits the terminal `result` event
-
-```typescript
-import { MemoryClient, type EnrichmentCallbacks, type FileIngestResult } from '@pyxmate/memory';
-
-const memory = new MemoryClient('http://localhost:7822', apiKey);
-
-const enrichment: EnrichmentCallbacks = {
-  // Optional: describe each image using LLM vision
-  describeImage: async (imageBuffer, meta) => {
-    // imageBuffer is ArrayBuffer of the extracted PNG/JPEG
-    // meta has: imageId, pageNumber, width, height, mimeType
-    return await myVisionModel.describe(imageBuffer);
-  },
-  // Optional: extract entities from text windows + image descriptions
-  extractEntitiesV2: async ({ textWindows, imageDescriptions, filename, mimeType }) => ({
-    entities: [{ name: 'Revenue', type: 'METRIC' }],
-    relationships: [{ source: 'Revenue', target: 'Q4', type: 'RELATED_TO' }],
-  }),
-};
-
-let result: FileIngestResult | null = null;
-for await (const event of memory.ingestFileEvents(pdfFile, { enrichment })) {
-  if (event.type === 'progress') {
-    console.log(`[${event.stage}] ${event.message ?? ''}`);
-    continue;
-  }
-  if (event.type === 'error') {
-    // Enrichment-stage errors (e.g. extractEntitiesV2 throws on a 401 storm)
-    // carry the server's pre-enrichment FileIngestResult under
-    // `partialResult` — the chunks/entryIds/catalog are durably stored.
-    // Persist them BEFORE surfacing the error so vector retrieval keeps
-    // working on the file. Parsing/storing/transport errors do not set it.
-    if (event.partialResult) {
-      result = event.partialResult;
-      // surface a "partial" status to the user, then throw to mark failure
-    }
-    throw new Error(event.message ?? event.error);
-  }
-  if (event.type === 'result') {
-    const { schemaVersion: _v, type: _t, stage: _s, message: _m, ...payload } = event;
-    result = payload;
-  }
-}
-if (!result) throw new Error('memory ingest stream ended without a result');
-```
-
-Without `enrichment` callbacks, the stream still emits `parsing` → `storing` progress events and a terminal `result` — the SDK just skips Phase 2/3.

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

@@ -1,344 +0,0 @@
-# pyx-memory Type Reference
-
-## Contents
-- Type Cheat Sheet
-- MemoryInterface (9 methods)
-- ExtendedMemoryInterface (10 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` |
-| `TenantScopeOptions` | `{ tenantId? }` | `@pyx-memory/client` |
-| `SensitivityLevel` | `'public' \| 'internal' \| 'secret'` | `@pyx-memory/shared` |
-| `MemoryClientOptions` | `{ apiKey?, defaultHeaders? }` | `@pyx-memory/client` |
-| `MemoryListParams` | `{ page?, limit?, type?, agentId?, tenantId? }` | `@pyx-memory/client` |
-| `MemoryListResult` | `{ entries, totalCount, page, limit }` | `@pyx-memory/client` |
-| `IngestionResult` | `{ filename, chunks, totalCharacters }` | `@pyx-memory/client` |
-| `FileIngestResult` | `IngestionResult & { enrichment?: EnrichmentPending }` | `@pyx-memory/shared` |
-| `EnrichmentPending` | `{ fileId, token, expiresAt, images: ExtractedImageMeta[] }` | `@pyx-memory/shared` |
-| `ExtractedImageMeta` | `{ imageId, pageNumber, width, height, mimeType }` | `@pyx-memory/shared` |
-| `EnrichmentCallbacks` | `{ describeImage, extractEntities? }` | `@pyx-memory/client` |
-| `EnrichRequest` | `{ imageDescriptions, entities?, relationships? }` | `@pyx-memory/shared` |
-| `EnrichResult` | `{ entryIds, entitiesStored, relationshipsStored }` | `@pyx-memory/shared` |
-| `ImageDescription` | `{ imageId, description }` | `@pyx-memory/shared` |
-| `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, options?: TenantScopeOptions): Promise<MemoryEntry | null>;
-  delete(id: string, options?: TenantScopeOptions): Promise<boolean>;
-  clearSession(sessionId: string, options?: TenantScopeOptions): Promise<number>;
-  stats(options?: TenantScopeOptions): Promise<MemoryStats>;
-  queryAsOf(asOfDate: string, filters?: TemporalQueryFilters): Promise<MemoryEntry[]>;
-  queryByEventTime(startTime: string, endTime: string, filters?: TemporalQueryFilters): Promise<MemoryEntry[]>;
-  shutdown(): Promise<void>;
-}
-```
-
-## ExtendedMemoryInterface (adds 10 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>;
-  // v0.18.0 — read-only memory-wide lint report (graph orphans, decay
-  // candidates, stale syntheses, content-hash dedup candidates).
-  lint(options?: { limit?: number }): Promise<WikiLintReport>;
-  // v0.18.1 — chronological feed (Karpathy log.md primitive). Cursor-style
-  // via `since` (created_at lower bound). No totalCount.
-  log(filters?: MemoryLogFilters): Promise<MemoryEntry[]>;
-  // v0.19.0 — entity synthesis (Karpathy "wiki page" primitive).
-  // summarizeEntity is LLM-driven and caller-triggered; it stores a pinned
-  // `_kind:'entity-summary'` entry with `_search_visibility:'on-demand'`
-  // (excluded from search). getEntitySynthesis is the O(1) read path.
-  summarizeEntity(name: string): Promise<MemoryEntry>;
-  getEntitySynthesis(name: string): Promise<MemoryEntry | null>;
-}
-```
-
-`MemoryLogFilters` = `{ since?: string; limit?: number; type?: MemoryType; agentId?: string; source?: string }`.
-
-### Reserved metadata conventions
-
-Some `metadata` keys carry behavior, not just data:
-
-| Key | Value | Effect |
-|-----|-------|--------|
-| `_search_visibility` | `'on-demand'` | Entry is excluded from every RAG engine's retrieval pool (v0.18.2 hook). Still reachable via `get` / `list` / `log` and deterministic-id fetch. Field absent ⇒ visible. |
-| `_kind` | `'entity-summary'` | Marks an entity synthesis. `Memory.lint` flags stale ones; the `synthesis:` id prefix is reserved for entries carrying this. |
-| `_sourceEntryIds` | `string[]` | Provenance — the entries a synthesis was built from. |
-| `_maxEventTime` | ISO string \| null | Staleness contract — `lint` flags the synthesis when a source's eventTime later exceeds this. |
-
-## MemoryClient Constructor and Concrete Methods
-
-```typescript
-// Constructor: URL required, second param is string (apiKey) or MemoryClientOptions
-const client = new MemoryClient('http://localhost:7822');                    // no auth
-const client = new MemoryClient('http://localhost:7822', 'my-api-key');     // with auth (string shorthand)
-const client = new MemoryClient('http://localhost:7822', process.env.MEMORY_API_KEY); // from env
-
-// Advanced: options object with default headers (e.g., multi-tenant access control)
-const client = new MemoryClient('http://localhost:7822', {
-  apiKey: 'my-api-key',
-  defaultHeaders: {
-    'X-Tenant-Id': 'tenant-abc',
-    'X-Caller-Access-Level': 'internal',
-  },
-});
-```
-
-When `apiKey` is provided, all requests include `Authorization: Bearer <key>`. Empty or whitespace-only keys are ignored. Default headers are merged into every request.
-
-`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 19 interface methods (9 base + 10 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 — native NDJSON streaming (v0.15.0+)
-  // Yields typed IngestEvents (progress / heartbeat / result / error).
-  // With enrichment callbacks: fetches extracted images, calls describeImage,
-  // calls extractEntitiesV2, posts /enrich, then yields the terminal `result`.
-  ingestFileEvents(file: File, options?: IngestFileOptions): AsyncIterable<IngestEvent>;
-
-  // 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
-  confidence?: {             // present when abstentionThreshold is set or strategy uses scoring
-    confidence: number;      // 0-1 confidence score
-    shouldAbstain: boolean;  // true when confidence < abstentionThreshold
-    signals: {
-      topScore: number;            // magnitude of the highest-scoring result
-      scoreGap: number;            // difference between #1 and #2 results
-      scoreStdDev: number;         // spread of scores (high = clear winner)
-      resultCount: number;         // how many results were returned
-      aboveThresholdRatio: number; // fraction of results above threshold
-      scoreSeparation: number;     // how much top-1 stands out from the pack
-    };
-  };
-}
-```
-
-## 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)
-  tenantId?: string;           // multi-tenant isolation (hard boundary)
-  userId?: string;             // user within tenant (legacy soft-scope)
-  teamId?: string;             // team/group within tenant (legacy soft-scope)
-  namespaceId?: string;        // ReBAC resource coordinate; NULL = legacy tenant-root bucket
-  sensitivity?: SensitivityLevel; // auto-classified: 'public' | 'internal' | 'secret'
-  encrypted?: boolean;         // true when content is encrypted at rest
-  pinned?: boolean;            // exempt from consolidation (decay-archive + dedup-merge); use for stable anchors referenced by external systems
-}
-```
-
-## 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
-  tenantId?: string;            // multi-tenant scoping
-  userId?: string;              // user-level scoping
-  teamId?: string;              // team-level scoping
-  /** Calling principal — drives ReBAC AuthzPlan. Search applies it as a
-   * native pre-filter on SQLite/FTS, vector, and graph layers; forbidden
-   * entries never enter RRF / reranker / abstention. Optional. */
-  principal?: PrincipalContext;
-  namespaceIds?: string[];      // populated internally from AuthzPlan — do not set directly
-  maxSensitivity?: SensitivityLevel; // filter by max sensitivity level
-  abstentionThreshold?: number; // 0-1, below this confidence → shouldAbstain=true (default: 0.3)
-}
-
-interface SearchFilters {
-  source?: string;
-  importanceMin?: number;
-  eventTimeRange?: [string, string];  // [start, end] ISO timestamps
-  parentId?: string;
-  contentType?: string;
-  excludePinned?: boolean;             // SQL-side `pinned = 0` filter (used internally by consolidation/decay; available to callers too)
-}
-```
-
-## PrincipalContext + ReBAC Types (v0.16.0+)
-
-The calling identity used to compute search-time AuthzPlan. Comes from
-authenticated request context (`X-Tenant-Id` + `X-User-Id` / `X-Agent-Id`),
-NEVER from request bodies.
-
-```typescript
-interface PrincipalContext {
-  tenantId: string;            // hard boundary; SINGLE_TENANT_ID sentinel in single mode
-  principalId: string;         // userId | agentId | service identifier
-  kind: 'user' | 'agent' | 'service';
-}
-
-interface Namespace {
-  id: string;
-  tenantId: string;
-  name: string;
-  parentId?: string;           // adjacency tree, max-depth 8
-  createdAt: string;
-  createdBy?: string;
-  metadata: Record<string, unknown>;
-}
-
-interface Principal {
-  id: string;
-  tenantId: string;
-  kind: 'user' | 'team' | 'group' | 'agent' | 'service' | 'everyone';
-  externalId?: string;         // maps to userId / agentId / teamId on entries
-  displayName?: string;
-  createdAt: string;
-  metadata: Record<string, unknown>;
-}
-
-interface AuthzTuple {
-  tenantId: string;
-  subjectKind: PrincipalKind;
-  subjectId: string;
-  subjectRelation?: string;    // for usersets like "members of team-eng"
-  relation: 'viewer' | 'editor' | 'owner' | string;
-  objectKind: 'namespace';     // v1 only supports namespace-level grants
-  objectId: string;
-  createdAt: string;
-  createdBy?: string;
-}
-
-interface AuthzPlan {
-  tenantId: string;
-  visibleNamespaceIds: string[];   // resolved + transitively expanded
-  visibleEntryOverrides: string[]; // reserved for v1.1
-  revision: string;                // bumps on every tuple/principal/membership mutation
-}
-```
-
-Built-in relation rewrite: `owner ⊇ editor ⊇ viewer`. Adding new relations
-is a code change, not a schema migration.
-
-In-process API: `Memory.authz` exposes `AuthzStore` with `createNamespace`,
-`upsertPrincipal`, `addMember`, `writeTuple`, `deleteTuple`, `buildAuthzPlan`
-etc. Sidecar / HTTP API: see [`http-api.md`](./http-api.md) §ReBAC Admin.
-
-## 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 |
-| `tenantId` | `string` | no | `undefined` | Auto-scopes ALL operations to this tenant (multi-tenant isolation) |
-| `encryptionKey` | `Buffer` | no | `undefined` | 32-byte AES-256-GCM key for encrypting `secret` entries at rest |
-| `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) |