@pyxmate/memory 0.6.0 → 0.6.1

package/README.md

@@ -26,7 +26,15 @@ This copies skill files into `.claude/skills/pyx-memory/` so Claude Code auto-di
 import { MemoryClient } from '@pyxmate/memory';
 import type { MemoryEntry } from '@pyxmate/memory';
 
-const client = new MemoryClient('https://your-pyx-memory-endpoint');
+// Simple: URL + API key
+const client = new MemoryClient('https://your-pyx-memory-endpoint', process.env.MEMORY_API_KEY);
+
+// Multi-tenant: URL + options with default headers
+const client = new MemoryClient('https://your-pyx-memory-endpoint', {
+  apiKey: process.env.MEMORY_API_KEY,
+  defaultHeaders: { 'X-Tenant-Id': 'tenant-abc' },
+});
+
 await client.initialize();
 
 // Store a memory

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyxmate/memory",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "type": "module",
   "description": "SDK for pyx-memory — Memory as a Service for AI agents",
   "license": "MIT",

package/skills/pyx-memory/SKILL.md

@@ -6,12 +6,15 @@ description: >
   remember something, recall prior context, store a decision or bug fix, ingest
   files or images, or search for what was discussed before. Also use when
   integrating the pyx-memory SDK into code, working with MemoryClient, or using
-  the HTTP API.
+  the HTTP API. Covers multi-tenant isolation (tenantId, TENANT_MODE),
+  sensitivity classification, encryption at rest, and confidence/abstention.
   Triggers on: 'remember', 'recall', 'store memory', 'search memory',
   'ingest file', 'store this image', 'remember this document',
   'what did we decide', 'pyx-memory', 'memory', 'MemoryClient',
-  'integrate memory', 'memory consolidation'.
-allowed-tools: Read, Grep, Glob, Bash(curl *)
+  'integrate memory', 'memory consolidation', 'multi-tenant',
+  'tenant isolation', 'sensitivity', 'encryption', 'confidence',
+  'abstention'.
+allowed-tools: Read, Grep, Glob, Edit, Write, Bash(curl *)
 argument-hint: "[store|search|ingest] <content or query>"
 ---
 
@@ -44,6 +47,16 @@ curl -s -X POST {{ENDPOINT}}/api/memory/ingest \
   -d '{"content":"WHAT_HAPPENED","type":"long-term","metadata":{"source":"agent","topic":"TOPIC","project":"PROJECT_NAME"}}'
 ```
 
+**Multi-tenant mode**: When the server uses `TENANT_MODE=multi`, include `X-Tenant-Id` on all requests:
+
+```bash
+curl -s -X POST {{ENDPOINT}}/api/memory/ingest \
+  -H "Authorization: Bearer {{API_KEY}}" \
+  -H "Content-Type: application/json" \
+  -H "X-Tenant-Id: {{TENANT_ID}}" \
+  -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
@@ -60,6 +73,8 @@ curl -s "{{ENDPOINT}}/api/memory/search?q=QUERY&limit=5" \
   -H "Authorization: Bearer {{API_KEY}}"
 ```
 
+**Multi-tenant mode**: Add `-H "X-Tenant-Id: {{TENANT_ID}}"` to scope search results to the tenant.
+
 ## Ingest files & images: when a file is worth remembering
 
 Upload files directly when the content is worth persisting — diagrams, screenshots, documents, data files.

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

@@ -21,7 +21,15 @@ const MEMORY_URL = process.env.MEMORY_URL; // e.g., 'http://localhost:7822'
 let memory: MemoryClient | null = null;
 
 if (MEMORY_URL) {
+  // Simple: API key only
   memory = new MemoryClient(MEMORY_URL, process.env.MEMORY_API_KEY);
+
+  // Multi-tenant: API key + tenant headers
+  // memory = new MemoryClient(MEMORY_URL, {
+  //   apiKey: process.env.MEMORY_API_KEY,
+  //   defaultHeaders: { 'X-Tenant-Id': 'tenant-abc', 'X-User-Id': 'user-123' },
+  // });
+
   await memory.initialize(); // verifies connectivity
 }
 
@@ -100,8 +108,11 @@ services:
       - memory-data:/data
     environment:
       - DATA_DIR=/data
+      - API_KEY=${MEMORY_API_KEY}              # auth for all requests
+      # - TENANT_MODE=multi                    # require X-Tenant-Id on all ops
+      # - SENSITIVITY_POLICY=encrypt           # encrypt secret entries at rest
+      # - ENCRYPTION_KEY=${ENCRYPTION_KEY}     # 32 bytes as 64 hex chars
       # Embedding is internal (BGE-M3, 1024d) — no API keys needed
-      # - EMBEDDING_DIMENSIONS=1024  # optional override
 
   your-app:
     environment:

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

@@ -37,6 +37,32 @@ await memory.initialize();
 // No external embedding provider needed
 ```
 
+## Pattern 2b: Production with Multi-Tenant + Encryption
+
+```typescript
+import { Memory } from '@pyx-memory/core';
+
+const memory = new Memory({
+  dataDir: './data',
+  tenantId: 'tenant-abc',       // Auto-scope all operations to this tenant
+  encryptionKey: Buffer.from(process.env.ENCRYPTION_KEY!, 'hex'), // 32 bytes for AES-256-GCM
+});
+await memory.initialize();
+
+// All store/search/get/delete/list operations are automatically tenant-scoped
+await memory.store({
+  content: 'Secret API key: sk-abc123',  // auto-classified as 'secret', encrypted at rest
+  type: 'long-term',
+  metadata: { source: 'config' },
+});
+
+// Search respects tenant isolation + sensitivity filtering
+const results = await memory.search({
+  query: 'API key',
+  maxSensitivity: 'internal', // 'secret' entries are redacted in results
+});
+```
+
 ## Pattern 3: Production with Store Targets
 
 ```typescript

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

@@ -105,11 +105,130 @@ Communities are leveraged by the hybrid RAG strategy to answer broad "what are t
 
 ---
 
+## Multi-Tenant Isolation
+
+pyx-memory supports multi-tenant data isolation via three scoping fields: `tenantId`, `userId`, and `teamId`.
+
+### Embedded mode
+
+```typescript
+// Instance-level scoping — auto-scopes ALL operations
+const memory = new Memory({
+  dataDir: './data',
+  tenantId: 'tenant-abc',
+});
+
+// Or per-operation scoping
+await memory.store({
+  content: 'Fact for this tenant.',
+  tenantId: 'tenant-abc',
+  userId: 'user-123',
+  teamId: 'team-eng',
+});
+
+// Search is auto-scoped to the instance tenantId
+const results = await memory.search({ query: 'facts', limit: 5 });
+
+// get/delete/clearSession/stats accept TenantScopeOptions
+const entry = await memory.get('entry-id', { tenantId: 'tenant-abc' });
+```
+
+### Sidecar mode
+
+```typescript
+// Set tenant headers via MemoryClientOptions
+const memory = new MemoryClient('http://localhost:7822', {
+  apiKey: process.env.MEMORY_API_KEY,
+  defaultHeaders: { 'X-Tenant-Id': 'tenant-abc', 'X-User-Id': 'user-123' },
+});
+
+// Or pass tenantId per-operation in the request body
+await memory.store({
+  content: 'Tenant-scoped memory.',
+  tenantId: 'tenant-abc',
+  userId: 'user-123',
+});
+```
+
+### Server enforcement
+
+Set `TENANT_MODE=multi` to require `X-Tenant-Id` on all operations. Requests without it are rejected (HTTP 400). When `TENANT_MODE=single` (default), tenant fields are stored but not enforced — backward compatible.
+
+Content hash dedup is scoped by `tenantId` to prevent cross-tenant collisions.
+
+---
+
+## Sensitivity Classification & Encryption
+
+pyx-memory auto-classifies content sensitivity and optionally encrypts sensitive data at rest.
+
+### How it works
+
+1. Every `store()` scans content for credentials and PII
+2. Auto-classifies as `public`, `internal` (PII), or `secret` (credentials)
+3. Behavior depends on `SENSITIVITY_POLICY` env var (or embedded config):
+   - `flag`: classify only, no content modification (default)
+   - `redact`: replace detected credentials with `[REDACTED]`
+   - `block`: reject ingestion (HTTP 400)
+   - `encrypt`: encrypt `secret` entries at rest with AES-256-GCM
+
+### Embedded encryption
+
+```typescript
+const memory = new Memory({
+  dataDir: './data',
+  encryptionKey: Buffer.from(process.env.ENCRYPTION_KEY!, 'hex'), // 32 bytes
+});
+
+// Entries classified as 'secret' are automatically encrypted before storage
+// Decryption is automatic on get() when the encryption key is available
+```
+
+### Search access control
+
+```typescript
+// Embedded: filter by max sensitivity
+const results = await memory.search({
+  query: 'config',
+  maxSensitivity: 'internal', // secret entries are redacted in results
+});
+
+// Sidecar: via header
+const memory = new MemoryClient('http://localhost:7822', {
+  apiKey: 'key',
+  defaultHeaders: { 'X-Caller-Access-Level': 'internal' },
+});
+```
+
+---
+
+## Confidence / Abstention
+
+Search results can include a confidence score that enables "I don't know" responses when retrieval quality is low.
+
+```typescript
+const results = await memory.search({
+  query: 'user preferences',
+  strategy: 'hybrid',
+  abstentionThreshold: 0.5, // 0-1, default 0.3
+});
+
+if (results.confidence?.shouldAbstain) {
+  // Confidence is below threshold — don't use these results
+  return "I don't have enough information to answer that.";
+}
+```
+
+The confidence score is computed from four signals: top score magnitude, score gap (top vs second), score spread (stdDev), and score separation (top vs mean). It's automatically included when using hybrid, graph, or agentic strategies.
+
+---
+
 ## Automatic Behaviors
 
 These happen automatically — no configuration needed:
 
 - **PII detection**: Every `store()` scans content and sets `metadata.piiDetected` + `metadata.piiTypes` if found
+- **Sensitivity classification**: Every `store()` auto-classifies content as `public`, `internal`, or `secret`
 - **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
@@ -117,6 +236,7 @@ These happen automatically — no configuration needed:
 - **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
+- **Tenant scoping**: If `tenantId` is set in MemoryOptions, all operations auto-filter by that tenant
 
 ---
 

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

@@ -36,7 +36,7 @@ const client = new MemoryClient('http://localhost:7822', process.env.MEMORY_API_
 | DELETE | `/api/memory/entries/:id` | Delete entry |
 | DELETE | `/api/memory/sessions/:sessionId` | Clear session |
 
-## Graph (4 endpoints)
+## Graph (5 endpoints)
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
@@ -44,6 +44,7 @@ const client = new MemoryClient('http://localhost:7822', process.env.MEMORY_API_
 | GET | `/api/memory/graph/edges` | Graph stats |
 | GET | `/api/memory/graph/relationships` | List relationships |
 | POST | `/api/memory/graph/query` | Traverse (JSON: `{ nodeId, depth? }`) |
+| POST | `/api/memory/graph/clear` | Clear all graph nodes and edges (admin) |
 
 ## Lifecycle (9 endpoints)
 
@@ -252,6 +253,86 @@ curl -s -X POST {{ENDPOINT}}/api/memory/ingest \
 
 ---
 
+## Multi-Tenant Isolation
+
+When `TENANT_MODE=multi`, the server requires `X-Tenant-Id` on all operations. Requests without it are rejected with HTTP 400.
+
+### Tenant Headers
+
+| Header | Description |
+|--------|-------------|
+| `X-Tenant-Id` | **Required** in multi-tenant mode. Tenant ID for data isolation. |
+| `X-User-Id` | Optional. User ID within the tenant. |
+| `X-Team-Id` | Optional. Team/group ID within the tenant. |
+
+As a fallback, `tenantId` can be extracted from JWT Bearer token claims (`tenantId`, `tenant_id`, or `tid` field in the payload).
+
+### Example: multi-tenant ingest
+
+```bash
+curl -X POST {{ENDPOINT}}/api/memory/ingest \
+  -H "Authorization: Bearer {{API_KEY}}" \
+  -H "Content-Type: application/json" \
+  -H "X-Tenant-Id: tenant-abc" \
+  -H "X-User-Id: user-123" \
+  -H "X-Team-Id: team-eng" \
+  -d '{"content":"Tenant-scoped memory.","type":"long-term","metadata":{}}'
+```
+
+Tenant scoping is enforced on all operations: ingest, search, list, get, delete, clearSession, stats.
+
+When `TENANT_MODE=single` (default), no tenant filtering applies (backward compatible). Tenant fields in the request body are still stored but not enforced.
+
+---
+
+## Sensitivity Classification & Encryption
+
+pyx-memory auto-classifies content sensitivity and optionally encrypts sensitive data at rest.
+
+### Sensitivity levels
+
+| Level | Auto-detected when |
+|-------|--------------------|
+| `public` | Neither credentials nor PII detected |
+| `internal` | PII detected (email, phone, SSN, etc.) |
+| `secret` | API keys, tokens, connection strings, private keys, passwords detected |
+
+### Sensitivity policy (`SENSITIVITY_POLICY` env var)
+
+| Policy | Behavior |
+|--------|----------|
+| `flag` (default) | Detect and classify. Store `sensitivity` field on entry. No content modification. |
+| `redact` | Replace detected credentials with `[REDACTED]` before storage. |
+| `block` | Reject ingest requests containing credentials (HTTP 400). |
+| `encrypt` | Entries classified as `secret` are encrypted at rest with AES-256-GCM. |
+
+### Search access control
+
+The `maxSensitivity` search parameter (or `X-Caller-Access-Level` header) filters results by sensitivity level. Entries above the caller's access level have their content replaced with `[REDACTED: sensitive content]`.
+
+```bash
+# Only see public and internal entries (secret entries are redacted)
+curl '{{ENDPOINT}}/api/memory/search?query=config' \
+  -H "Authorization: Bearer {{API_KEY}}" \
+  -H "X-Caller-Access-Level: internal"
+```
+
+---
+
+## Confidence / Abstention
+
+Search results include optional confidence scoring via the `abstentionThreshold` parameter.
+
+```bash
+# Get confidence scoring with custom threshold (0-1, default 0.3)
+curl '{{ENDPOINT}}/api/memory/search?query=user+preferences&strategy=hybrid&abstentionThreshold=0.5'
+# Response includes: { confidence: { confidence: 0.72, shouldAbstain: false, signals: { ... } } }
+```
+
+When `shouldAbstain` is `true`, the retrieval confidence is below the threshold — the agent should respond with "I don't know" rather than using low-confidence results.
+
+---
+
 ## Response Format
 
 All responses follow: `{ success: boolean, data?: T, error?: string }`
@@ -274,8 +355,11 @@ All responses follow: `{ success: boolean, data?: T, error?: string }`
 | `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 |
+| `MAX_REQUEST_BODY_MB` | `512` | 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) |
+| `SENSITIVITY_POLICY` | `flag` | Credential sensitivity handling: `flag` (detect + classify), `redact` (replace with [REDACTED]), `block` (reject 400), `encrypt` (AES-256-GCM at rest) |
+| `ENCRYPTION_KEY` | — | AES-256-GCM encryption key for sensitive content at rest (32 bytes as 64 hex chars or 44 base64 chars). Required when `SENSITIVITY_POLICY=encrypt` |
 | `RATE_LIMIT_RPM` | `0` | Requests per minute per IP. 0 = disabled |
+| `TENANT_MODE` | `single` | Tenant isolation mode: `single` (no tenant filtering, backward compatible) or `multi` (require `X-Tenant-Id` header on all operations) |
 | `ENRICHMENT_SECRET` | (auto-generated) | HMAC secret for enrichment token signing. Auto-generated if unset (tokens won't survive restarts). Min 32 bytes for production. |

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

@@ -20,6 +20,10 @@
 | id (custom) | yes | yes |
 | parentId | yes | yes |
 | ingestTime | yes | yes |
+| tenantId | yes | yes |
+| userId | yes | yes |
+| teamId | yes | yes |
+| sensitivity | yes | yes (auto-classified) |
 
 **All StoreInput fields are forwarded.** Full parity.
 
@@ -28,6 +32,9 @@
 | Param | Embedded `Memory.search()` | Sidecar `MemoryClient.search()` |
 |-------|---------------------------|--------------------------------|
 | query, limit, type, agentId, strategy | yes | yes |
+| tenantId, userId, teamId | yes | yes (via `X-Tenant-Id`/`X-User-Id`/`X-Team-Id` headers or `defaultHeaders` — NOT forwarded from per-request params) |
+| maxSensitivity | yes | yes (via `X-Caller-Access-Level` header or `defaultHeaders` — NOT forwarded from per-request params) |
+| abstentionThreshold | yes | yes |
 | eventTimeRange (bi-temporal search) | yes | yes |
 | asOf (point-in-time search) | yes | yes |
 | **filters** (source, importanceMin, parentId, contentType) | yes | **NO** — not forwarded |
@@ -42,6 +49,7 @@
 |----------------|-------------|-----------------|
 | All core (9) | yes | yes (inherited) |
 | Graph nodes/edges/query (3) | yes (concrete methods) | yes (inherited) |
+| Graph clear (admin) | yes (`graphClear()`) | yes (inherited) |
 | **Graph relationships** | **NO** | yes (`graphRelationships()`) |
 | All lifecycle (7) | yes | yes (inherited) |
 | **Consolidation log** | **NO** | yes (`consolidationLog()`) |
@@ -59,5 +67,8 @@
 | 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) |
+| Sensitivity policy | `SENSITIVITY_POLICY` env var (`flag` / `redact` / `block` / `encrypt`) |
+| Encryption at rest | `ENCRYPTION_KEY` env var (32 bytes, hex or base64) |
+| Multi-tenant isolation | `TENANT_MODE` env var (`single` / `multi`) |
+| Body size limit | `MAX_REQUEST_BODY_MB` env var (default: 512) |
 | Error masking | 5xx details hidden when `NODE_ENV=production` |

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

@@ -77,6 +77,15 @@ 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: {} });
@@ -122,6 +131,8 @@ Start the server: `bun packages/server/src/index.ts`
 - **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
 
@@ -132,6 +143,7 @@ Start the server: `bun packages/server/src/index.ts`
 - **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
 

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

@@ -25,7 +25,10 @@
 | `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` |
+| `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` |
@@ -49,10 +52,12 @@ interface MemoryInterface {
   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>;
+  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>;
 }
 ```
@@ -73,13 +78,22 @@ interface ExtendedMemoryInterface extends MemoryInterface {
 ## MemoryClient Constructor and Concrete Methods
 
 ```typescript
-// Constructor: URL required, apiKey optional
+// 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
+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.
+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`.
@@ -138,6 +152,18 @@ interface MemorySearchResult {
   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
+    };
+  };
 }
 ```
 
@@ -161,6 +187,11 @@ interface MemoryEntry {
   source?: string;             // filename, URL, session ID
   eventTime?: string;          // when event happened (bi-temporal)
   ingestTime?: string;         // when stored (bi-temporal)
+  tenantId?: string;           // multi-tenant isolation
+  userId?: string;             // user within tenant
+  teamId?: string;             // team/group within tenant
+  sensitivity?: SensitivityLevel; // auto-classified: 'public' | 'internal' | 'secret'
+  encrypted?: boolean;         // true when content is encrypted at rest
 }
 ```
 
@@ -176,6 +207,11 @@ interface MemorySearchParams {
   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
+  maxSensitivity?: SensitivityLevel; // filter by max sensitivity level
+  abstentionThreshold?: number; // 0-1, below this confidence → shouldAbstain=true (default: 0.3)
 }
 
 interface SearchFilters {
@@ -201,6 +237,8 @@ interface SearchFilters {
 | `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