@pyxmate/memory 0.20.5 → 0.21.1

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

@@ -1,526 +0,0 @@
-# pyx-memory HTTP API Reference
-
-## Authentication
-
-When the server has `API_KEY` configured, all requests (except `/health` and enrichment routes) 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`).
-
-**Enrichment routes** (`/api/memory/files/*`) use HMAC token auth instead of API keys. Tokens are issued by the server during file ingestion and are short-lived (30 minutes).
-
-`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 (13 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, namespaceId?, agentId?, sessionId?, targets?, entities?, relationships?, importance?, source?, eventTime?, id?, parentId?, ingestTime?, pinned? }`) |
-| POST | `/api/memory/ingest/file` | Upload file (multipart, 100MB limit; optional `namespaceId` field or `X-Namespace-Id` header). For PDFs with images, returns an `enrichment` block with HMAC token and image metadata for two-phase enrichment. |
-| GET | `/api/memory/files/download/:filename` | Download uploaded file binary by filename. Returns the original file with proper Content-Type. Images served inline, documents as attachment. |
-| GET | `/api/memory/files/:fileId/images/:imageId?token=...` | Fetch an extracted PDF image (binary). Requires HMAC token from ingest response. |
-| POST | `/api/memory/files/:fileId/enrich` | Submit image descriptions + entities after LLM vision processing. Requires `X-Enrichment-Token` header. |
-| 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 (5 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? }`) |
-| POST | `/api/memory/graph/clear` | Clear all graph nodes and edges (admin) |
-
-## Lifecycle (13 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) |
-| GET | `/api/memory/lint` | Read-only memory-wide lint report — graph orphans, decay candidates, stale syntheses, dedup candidates (v0.18.0) |
-| GET | `/api/memory/log?since=...` | Chronological feed (Karpathy `log.md`). Cursor-style via `since` created_at lower bound; also `limit`, `type`, `agentId`, `source`. Returns `{ entries, count, since? }` (v0.18.1) |
-| POST | `/api/memory/synthesis/entity` | Synthesize a per-entity profile (Karpathy "wiki page"). JSON: `{ name }`. LLM-driven; stores a pinned `_kind:'entity-summary'` entry with `_search_visibility:'on-demand'`. Returns the entry, 201 (v0.19.0) |
-| GET | `/api/memory/synthesis/entity?name=...` | Fetch a previously-synthesized entity profile. Returns `{ entry }` (`null` if none) (v0.19.0) |
-
-## ReBAC Admin (11 endpoints)
-
-Fine-grained access control inside a tenant — namespaces, principals, group membership, and authz tuples. All routes require `ADMIN_API_KEY` and an `X-Tenant-Id` header. See [`patterns/access-control.md`](../patterns/access-control.md) Pattern 15 for the full guide.
-
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| POST | `/api/admin/namespaces` | Create namespace (JSON: `{ name, parentId?, metadata?, createdBy? }`) |
-| GET | `/api/admin/namespaces` | List namespaces in this tenant |
-| DELETE | `/api/admin/namespaces/:id` | Delete namespace + tuples referencing it (RESTRICT on children) |
-| POST | `/api/admin/principals` | Upsert principal (JSON: `{ kind, externalId?, displayName?, metadata? }`) |
-| GET | `/api/admin/principals` | List principals in this tenant |
-| DELETE | `/api/admin/principals/:id` | Delete principal + cascade memberships |
-| POST | `/api/admin/principal-members` | Add member to group (JSON: `{ groupId, memberId }`) — cycle-checked |
-| DELETE | `/api/admin/principal-members/:groupId/:memberId` | Remove membership |
-| POST | `/api/admin/authz-tuples` | Write tuple (JSON: `{ subjectKind, subjectId, subjectRelation?, relation, objectKind, objectId, createdBy? }`) |
-| GET | `/api/admin/authz-tuples?objectId=&subjectId=` | List tuples (filterable) |
-| DELETE | `/api/admin/authz-tuples` | Delete tuple (JSON: same body shape as POST) |
-
-`kind`: `'user' | 'team' | 'group' | 'agent' | 'service' | 'everyone'`. `objectKind` is `'namespace'` only in v1. `relation` is freeform (built-in rewrite: `owner ⊇ editor ⊇ viewer`).
-
-Cross-tenant safety: every route verifies the referenced resource belongs to the caller's tenant; mismatches return `404` (not `403`) to avoid existence disclosure.
-
-## Namespaced Ingest (v0.17.1)
-
-`POST /api/memory/ingest` accepts `namespaceId` either in the JSON body or the `X-Namespace-Id` header. `POST /api/memory/ingest/file` accepts the same header or a multipart `namespaceId` field. The header is canonical; sending both channels with different values returns `400 namespace_id_conflict`. Sending JSON `namespaceId: null` is invalid; omit the field to keep the legacy NULL namespace bucket.
-
-When a namespace is supplied, the server resolves it once against the caller tenant before storing. Missing or cross-tenant namespaces return `404 namespace_not_found` so callers cannot distinguish "does not exist" from "exists in another tenant".
-
-```bash
-curl -X POST {{ENDPOINT}}/api/memory/ingest \
-  -H "Authorization: Bearer {{API_KEY}}" \
-  -H "X-Tenant-Id: tenant-acme" \
-  -H "X-Namespace-Id: ns-engineering" \
-  -H "Content-Type: application/json" \
-  -d '{"content":"Q4 revenue projections","type":"long-term"}'
-```
-
-## Strict Topology Isolation (v0.17.0)
-
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| POST | `/api/admin/namespaces/:id/isolation` | Toggle isolation. Body: `{ isolation: 'shared' \| 'strict' }`. Returns `{ namespace, changed }` — `changed: false` means the no-op path (already in the requested mode); revision unchanged. |
-
-Effect of `strict`:
-
-- Graph traversal (`/api/memory/graph/query` and indirect uses inside `/api/memory/search`) drops edges whose `namespace_id` matches `AuthzPlan.forbiddenStrictNamespaceIds`.
-- `/api/memory/graph/nodes` and `/api/memory/graph/relationships` apply the AuthzPlan at the HTTP boundary. Node projection intersects `memoryEntryIds` with the visible set and strips provenance properties (`source`, `sourceUrl`, `sourceTitle`, `sourceUri`, `url`, `title`).
-- Effect propagates immediately — the toggle bumps the per-tenant AuthzPlan revision, so cached plans pick up `forbiddenStrictNamespaceIds` on the next request.
-
-## Idempotent Admin Mutations (v0.17.0)
-
-All `/api/admin/*` mutation routes (POST / DELETE / PUT) honor the `X-Idempotency-Key` request header. A replay with the same key — within the 24h TTL — returns the previously recorded response body + status without re-executing the handler. Set the header from the BFF / sweeper:
-
-```bash
-curl -X POST "$ENDPOINT/api/admin/namespaces" \
-  -H "Authorization: Bearer $ADMIN_API_KEY" \
-  -H "X-Tenant-Id: $TENANT" \
-  -H "X-Idempotency-Key: $(uuidgen)" \
-  -H "Content-Type: application/json" \
-  -d '{"name":"engineering"}'
-```
-
-GET / OPTIONS / HEAD bypass the wrapper entirely (read-only methods are safe to retry). The header is OPTIONAL — callers that don't set it get the legacy fire-and-forget behavior.
-
-## Entry Move Admin (v0.16.1)
-
-Reassign existing entries to a target namespace — the migration path for legacy NULL-namespace data and any later reorganization. Both routes are gated by `ADMIN_API_KEY` and require `X-Tenant-Id`. See [`patterns/access-control.md`](../patterns/access-control.md) Pattern 15 § "Migrating legacy entries" for the workflow.
-
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| POST | `/api/admin/entries/:id/move` | Single move (JSON: `{ namespaceId: string \| null }`) |
-| POST | `/api/admin/entries/move-batch` | Batch move with cursor + dryRun (JSON: `{ filter, target, limit?, dryRun? }`) |
-
-**Single response** — `200 OK` with the standard `{ success: true, data: T }` envelope wrapping a `MoveResult`:
-
-```json
-{
-  "success": true,
-  "data": {
-    "entryId": "entry-abc",
-    "success": true,
-    "fromNamespaceId": null,
-    "toNamespaceId": "ns-engineering"
-  }
-}
-```
-
-The inner `success: false` flag carries `failureReason` ∈ `{ not_found, cross_tenant_forbidden, target_namespace_not_found, sqlite_update_failed, vector_update_failed, graph_update_failed, compensation_failed }`. The route never returns 2xx with a failed inner result — instead it maps the failureReason to HTTP status as: `not_found` → 404, `cross_tenant_forbidden` / `target_namespace_not_found` → 400, store failures (`sqlite_update_failed` / `vector_update_failed` / `graph_update_failed`) → 502, `compensation_failed` → 500. The error body uses the project's standard `{ success: false, error: string }` envelope.
-
-**Batch body shape**:
-
-```json
-{
-  "filter": {
-    "fromNamespaceId": "ns-old" | null,
-    "entryIds": ["..."],
-    "agentId": "...", "teamId": "...", "userId": "...", "source": "...",
-    "limit": 100,
-    "cursor": "<opaque>"
-  },
-  "target": { "namespaceId": "ns-new" | null },
-  "dryRun": true,
-  "limit": 100
-}
-```
-
-`filter.fromNamespaceId` is required (footgun guard — there is no "move every entry I can see" form). `target.namespaceId: null` reverts entries to tenant-root. `dryRun: true` returns the prospective `MoveResult[]` without touching any store; `dryRun: false` (default) executes. Response carries `nextCursor` when more rows match — feed it back via `filter.cursor` for the next page.
-
-## File Ingestion (Images + Documents)
-
-`POST /api/memory/ingest/file` accepts multipart/form-data with:
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `file` | File | Yes | The file to ingest (max 100MB) |
-| `description` | string | No | Agent-provided description (e.g., from LLM vision). Used instead of parser output for images. |
-| `namespaceId` | string | No | ReBAC namespace to stamp on every chunk. `X-Namespace-Id` header is preferred when both are present. |
-
-**Supported formats**: `.txt`, `.md`, `.csv`, `.tsv`, `.log`, `.pdf`, `.docx`, `.xlsx`, `.pptx`, `.json`, `.jsonl`, `.html`, `.htm`, `.png`, `.jpg`, `.jpeg`, `.webp`, `.gif`, `.bmp`, `.tiff`, `.svg`
-
-**Memory behavior, by format**:
-
-- **Plain-text + structured-text** (`csv`, `tsv`, `txt`, `log`, `json`, `jsonl`, `html`, `htm`, `md`) — fully streaming; peak server memory ≈ a few MB regardless of file size up to the 100 MB cap.
-- **`pdf`** — streaming via `pdftotext` (poppler-utils); fall-back path (`pdf-parse`) buffers the file, so install poppler-utils on the server for streaming behavior.
-- **`xlsx`** — `ExcelJS.stream.xlsx.WorkbookReader` yields rows as it parses, but the shared-string table is cached for the whole workbook. Peak memory grows with shared-string count; dense workbooks can exceed "a few MB" significantly.
-- **`pptx`** — the full ZIP is decompressed in memory (~3× file size peak for typical decks). One slide's XML is decoded at a time. Bounded by the 100 MB file cap and a 200 MB decompressed cap.
-- **`docx`** — hard-capped at 10 MB. mammoth has no streaming API; above 10 MB the server returns a `MemoryError` asking you to pre-extract the text upstream and re-upload as `.txt` or `.md`.
-
-For deterministic peak memory or timing (production UX), consumers should pre-extract `.pptx` and large `.xlsx` upstream and upload the text as `.txt` — see `patterns/file-uploads.md`.
-
-**What happens on upload**:
-1. Original file is saved to `{DATA_DIR}/files/{filename}` (persistent across restarts)
-2. Text is extracted (documents) or description is used (images)
-3. Content is chunked and stored in SQLite + vector for semantic search
-4. Source-aware dedup: re-uploading the same filename replaces the previous version
-5. **PDFs with images**: Images are extracted via poppler (`pdfimages` for embedded objects, `pdftoppm` for page renders on scanned PDFs), saved to a temp directory, and an `enrichment` block is returned with HMAC-signed tokens for two-phase enrichment. `pdf-parse` is used only as a dev fallback for small files (<5MB) when poppler isn't installed.
-
-**Image ingestion**: Images cannot have text extracted. Pass a `description` field with a natural-language description (e.g., from an LLM with vision). Without a description, images get a minimal placeholder (`[Image] filename (size KB)`).
-
-**PDF enrichment**: When a PDF contains images (≥50x50px), the server emits an `enrichment` block on the terminal `result` event. The SDK's `ingestFileEvents()` with `EnrichmentCallbacks` handles the full flow automatically — see [sdk-guide.md](sdk-guide.md#two-phase-pdf-enrichment).
-
-### NDJSON Wire Format (the only response shape)
-
-`POST /api/memory/ingest/file` always streams `Content-Type: application/x-ndjson`. Each line is one typed event with `schemaVersion: 1`. The terminal event is exactly one of `result` (success) or `error` (failure):
-
-```
-{"schemaVersion":1,"type":"progress","stage":"parsing","filename":"large-report.pdf","message":"Extracting text..."}
-{"schemaVersion":1,"type":"progress","stage":"storing","filename":"large-report.pdf","chunksStored":10,"totalCharacters":4800}
-{"schemaVersion":1,"type":"heartbeat","stage":"storing","message":"File ingest still running"}
-{"schemaVersion":1,"type":"progress","stage":"enrichment","filename":"large-report.pdf"}
-{"schemaVersion":1,"type":"result","stage":"complete","filename":"large-report.pdf","fileType":".pdf","chunks":24,"entryIds":["…"],"totalCharacters":11520}
-```
-
-**Stable stages**: `parsing` (text/image extraction), `storing` (chunk + vector writes), `enrichment` (LLM image-describe + entity-extract + `/enrich` POST), `complete` (terminal result only). Finer detail goes in optional counters (`chunksStored`, `totalCharacters`) and `message`, not in new stage names.
-
-**Heartbeat**: emitted every 20s while the pipeline is doing slow work. Sized below undici's default 300s `headersTimeout` and Envoy's default 5m stream-idle so an LLM call or graph batch never trips an upstream socket timeout.
-
-**Errors before the stream starts** (multipart parse, file size cap, validation) come back as a single-line NDJSON `error` event with the appropriate HTTP status code on the response.
-
-Pre-v0.15.0 servers returned `application/json` for this endpoint. v0.15.0 SDK consumers will see a terminal `error` event with the message `Memory server returned application/json instead of application/x-ndjson — server is older than v0.15.0` if they hit such a server; upgrade the server.
-
-### Example: ingest a document
-
-```bash
-curl -N -X POST {{ENDPOINT}}/api/memory/ingest/file \
-  -H "Authorization: Bearer {{API_KEY}}" \
-  -F "file=@report.pdf"
-```
-
-`-N` disables curl buffering so events appear as the server emits them.
-
-### Example: ingest an image with description
-
-```bash
-curl -N -X POST {{ENDPOINT}}/api/memory/ingest/file \
-  -H "Authorization: Bearer {{API_KEY}}" \
-  -F "file=@screenshot.png" \
-  -F "description=A screenshot of the dashboard showing memory usage at 85%"
-```
-
-### SDK usage
-
-```typescript
-import { MemoryClient, type FileIngestResult } from '@pyxmate/memory';
-
-// Iterate the AsyncIterable. The terminal event is `result` (success) or `error` (failure).
-async function ingestAndCollect(memory: MemoryClient, file: File): Promise<FileIngestResult> {
-  for await (const event of memory.ingestFileEvents(file)) {
-    if (event.type === 'progress' || event.type === 'heartbeat') continue;
-    if (event.type === 'error') throw new Error(event.message ?? event.error);
-    // event.type === 'result'
-    const { schemaVersion: _v, type: _t, stage: _s, message: _m, ...result } = event;
-    return result;
-  }
-  throw new Error('memory ingest stream ended without a terminal event');
-}
-
-// Document (text-only)
-const doc = new File([buffer], 'report.pdf', { type: 'application/pdf' });
-await ingestAndCollect(memory, doc);
-
-// Image with description
-const img = new File([imgBuffer], 'photo.png', { type: 'image/png' });
-await ingestAndCollect(memory, img); // pass via options when needed
-for await (const _ of memory.ingestFileEvents(img, {
-  description: 'A photo of the whiteboard from the architecture meeting',
-})) { /* drain */ }
-
-// PDF with two-phase enrichment (images described via LLM vision)
-for await (const event of memory.ingestFileEvents(pdfFile, {
-  enrichment: {
-    describeImage: async (buffer, meta) => 'A bar chart showing Q4 revenue growth of 23%',
-    extractEntitiesV2: async ({ textWindows, imageDescriptions, filename, mimeType }) => ({
-      entities: [{ name: 'Q4 Revenue', type: 'METRIC' }],
-      relationships: [],
-    }),
-  },
-})) {
-  if (event.type === 'progress') {
-    console.log(`[${event.stage}] ${event.message ?? ''}`);
-  }
-}
-```
-
-## File Downloads
-
-`GET /api/memory/files/download/:filename` serves uploaded file binaries.
-
-- **Images** (`image/*`): served inline (`Content-Disposition: inline`)
-- **Documents**: served as attachment (`Content-Disposition: attachment; filename="..."`)
-- **Caching**: `Cache-Control: public, max-age=86400, immutable`
-- **Auth**: standard API key auth (same as other endpoints)
-- **Security**: path traversal prevention, extension validation against ingestion allowlist
-
-### Example: download a file
-
-```bash
-curl -o report.pdf "{{ENDPOINT}}/api/memory/files/download/report.pdf" \
-  -H "Authorization: Bearer {{API_KEY}}"
-```
-
-### SDK usage
-
-```typescript
-// Get download URL (useful for markdown images, browser rendering)
-const url = memory.getFileDownloadUrl('screenshot.png');
-// → 'http://localhost:7822/api/memory/files/download/screenshot.png'
-
-// Download file binary
-const response = await memory.downloadFile('report.pdf');
-const buffer = await response.arrayBuffer();
-```
-
-## Two-Phase PDF Enrichment
-
-When a PDF contains extractable images, the server's terminal `result` event carries an `enrichment` block. The SDK's `ingestFileEvents()` with `EnrichmentCallbacks` runs the full three-phase flow automatically, emitting its own `enrichment` progress + heartbeat events while it works.
-
-### Flow
-
-```
-Phase 1: POST /api/memory/ingest/file → text stored immediately, enrichment block emitted on terminal `result`
-  Result event: { schemaVersion: 1, type: 'result', stage: 'complete', ...ingestResult, enrichment: { fileId, token, expiresAt, images: [...] } }
-
-Phase 2: GET /api/memory/files/{fileId}/images/{imageId}?token=... → binary image
-  (SDK fetches each image, calls describeImage callback)
-
-Phase 3: POST /api/memory/files/{fileId}/enrich
-  Header: X-Enrichment-Token: {token}:{expiresAt}
-  Body: { imageDescriptions: [...], entities?: [...], relationships?: [...] }
-  → descriptions stored as memory entries, temp images cleaned up
-```
-
-### Image fetch endpoint
-
-`GET /api/memory/files/:fileId/images/:imageId?token=<hmac>`
-
-Returns the binary image with `Content-Type: image/png` or `image/jpeg`. The HMAC token is issued by the server during Phase 1 and expires after 30 minutes.
-
-### Enrich endpoint
-
-`POST /api/memory/files/:fileId/enrich`
-
-| Header | Required | Description |
-|--------|----------|-------------|
-| `X-Enrichment-Token` | Yes | Format: `{hmac_token}:{expiresAt_iso}` |
-
-Body:
-```json
-{
-  "imageDescriptions": [
-    { "imageId": "uuid-img-0", "description": "A chart showing..." }
-  ],
-  "entities": [{ "name": "Revenue", "type": "METRIC" }],
-  "relationships": []
-}
-```
-
-Input limits: descriptions max 10,000 chars each, entities max 200, relationships max 500.
-
-### Security
-
-- Tokens are HMAC-SHA256 signed (server secret + fileId + expiresAt)
-- `fileId` must be a valid UUIDv4
-- `imageId` must match `^[a-zA-Z0-9_-]+$`
-- Image paths are sandboxed via `resolve()` + `startsWith()` to prevent path traversal
-- Enrichment routes bypass API key auth — they use their own HMAC verification
-
----
-
-## 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":[
-      {"source":"Alice","target":"TypeScript","type":"USES"},
-      {"source":"TypeScript","target":"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**: `source` (source entity name), `target` (target entity name), `type` (required). Legacy `{from, to}` aliases are also accepted by the pyx-cloud hosted wrapper at `memory.api.pyxmate.com` for backward compatibility, but `{source, target}` is canonical.
-
----
-
-## 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 }`
-
----
-
-## 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` | `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

@@ -1,74 +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 |
-| tenantId | yes | yes |
-| userId | yes | yes |
-| teamId | yes | yes |
-| sensitivity | yes | yes (auto-classified) |
-
-**All StoreInput fields are forwarded.** Full parity.
-
-## search() Param Parity
-
-| 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 |
-| **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 clear (admin) | yes (`graphClear()`) | 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`) |
-| 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` |