@pyxmate/memory 0.6.1 → 0.6.2

package/package.json

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

package/skills/pyx-memory/SKILL.md

@@ -13,7 +13,8 @@ description: >
   'what did we decide', 'pyx-memory', 'memory', 'MemoryClient',
   'integrate memory', 'memory consolidation', 'multi-tenant',
   'tenant isolation', 'sensitivity', 'encryption', 'confidence',
-  'abstention'.
+  'abstention', 'access control', 'RBAC', 'read-only', 'permissions',
+  'agent isolation', 'per-agent memory', 'role-based access'.
 allowed-tools: Read, Grep, Glob, Edit, Write, Bash(curl *)
 argument-hint: "[store|search|ingest] <content or query>"
 ---
@@ -114,6 +115,7 @@ For integrating pyx-memory into TypeScript/Bun projects, see the reference docs:
 |---|---|
 | Wire pyx-memory into a consumer project | [patterns/consumer.md](patterns/consumer.md) |
 | Set up embedded memory (full features) | [patterns/embedded.md](patterns/embedded.md) |
+| Multi-tenant, RBAC, sensitivity, encryption | [patterns/access-control.md](patterns/access-control.md) |
 | SDK quick start, package map, DO/DON'T | [reference/sdk-guide.md](reference/sdk-guide.md) |
 | HTTP API endpoints | [reference/http-api.md](reference/http-api.md) |
 | Type signatures and interfaces | [reference/types.md](reference/types.md) |

package/skills/pyx-memory/patterns/access-control.md

@@ -0,0 +1,381 @@
+# Access Control Patterns
+
+Production patterns for restricting who can read and write which memories.
+
+## Contents
+- [Quick Decision Tree](#quick-decision-tree)
+- [Pattern 10: Per-Agent Isolation](#pattern-10-per-agent-isolation)
+- [Pattern 11: Multi-Tenant with Team Scoping](#pattern-11-multi-tenant-with-team-scoping)
+- [Pattern 12: Sensitivity-Based Read Restriction](#pattern-12-sensitivity-based-read-restriction)
+- [Pattern 13: Read-Only vs Read-Write Access](#pattern-13-read-only-vs-read-write-access)
+- [Pattern 14: Full Production Stack](#pattern-14-full-production-stack)
+- [Architecture: Access Policy Layer](#architecture-access-policy-layer)
+
+---
+
+## Quick Decision Tree
+
+```
+Need to isolate agents from each other?
+  → Use agentId scoping (Pattern 10)
+
+Need to isolate organizations/customers?
+  → Use TENANT_MODE=multi + X-Tenant-Id (Pattern 11)
+
+Need to hide sensitive data from some users?
+  → Use sensitivity classification + X-Caller-Access-Level (Pattern 12)
+
+Need read-only vs read-write roles?
+  → Use API_KEY + ADMIN_API_KEY + an API gateway (Pattern 13)
+
+Need all of the above?
+  → Pattern 14 (full production stack)
+```
+
+---
+
+## Pattern 10: Per-Agent Isolation
+
+Each agent sees only its own memories. Other agents' memories are invisible — not redacted, just absent from results.
+
+```typescript
+// Agent A — can only see its own memories
+const agentAMemory = new Memory({
+  dataDir: './data',
+  agentId: 'agent-researcher',
+});
+await agentAMemory.initialize();
+
+// Anything agent A stores is tagged with agentId: 'agent-researcher'
+await agentAMemory.store({
+  content: 'Found a bug in the auth module',
+  type: 'long-term',
+  metadata: {},
+});
+
+// Agent A's searches only return agent A's memories
+const results = await agentAMemory.search({ query: 'auth bug' });
+// ✓ Returns the entry above
+
+// Agent B — completely isolated
+const agentBMemory = new Memory({
+  dataDir: './data',
+  agentId: 'agent-writer',
+});
+await agentBMemory.initialize();
+
+const bResults = await agentBMemory.search({ query: 'auth bug' });
+// ✗ Returns nothing — agent A's memories are invisible to agent B
+```
+
+**Sidecar mode**: Pass `agentId` in the request body or query params — the server filters by it.
+
+```bash
+# Store as agent-researcher
+curl -X POST http://localhost:7822/api/memory/ingest \
+  -H "Content-Type: application/json" \
+  -d '{"content":"Agent-scoped fact","type":"long-term","metadata":{},"agentId":"agent-researcher"}'
+
+# Search as agent-researcher — only sees agent-researcher's memories
+curl 'http://localhost:7822/api/memory/search?query=fact&agentId=agent-researcher'
+```
+
+**When to use**: Multiple AI agents sharing one memory instance, each needing their own knowledge base. Agents that should collaborate can omit `agentId` to share a global pool.
+
+---
+
+## Pattern 11: Multi-Tenant with Team Scoping
+
+For SaaS / multi-organization deployments where each customer's data must be completely isolated.
+
+### Server config
+
+```bash
+# docker-compose.yaml
+environment:
+  - TENANT_MODE=multi    # enforce X-Tenant-Id on ALL operations
+  - API_KEY=your-key     # always set API_KEY with multi-tenant
+```
+
+### Per-client setup
+
+```typescript
+import { MemoryClient } from '@pyx-memory/client';
+
+// Organization A — engineering team
+const orgAEng = new MemoryClient('http://memory:7822', {
+  apiKey: process.env.MEMORY_API_KEY,
+  defaultHeaders: {
+    'X-Tenant-Id': 'org-acme',
+    'X-User-Id': 'alice',
+    'X-Team-Id': 'team-engineering',
+  },
+});
+
+// Organization A — marketing team (same tenant, different team)
+const orgAMkt = new MemoryClient('http://memory:7822', {
+  apiKey: process.env.MEMORY_API_KEY,
+  defaultHeaders: {
+    'X-Tenant-Id': 'org-acme',
+    'X-User-Id': 'bob',
+    'X-Team-Id': 'team-marketing',
+  },
+});
+
+// Organization B — completely isolated tenant
+const orgB = new MemoryClient('http://memory:7822', {
+  apiKey: process.env.MEMORY_API_KEY,
+  defaultHeaders: {
+    'X-Tenant-Id': 'org-globex',
+    'X-User-Id': 'charlie',
+  },
+});
+```
+
+### What's enforced
+
+| Scope level | How it works |
+|-------------|-------------|
+| `tenantId` | **Hard isolation.** Tenant A never sees tenant B's data. Enforced server-side when `TENANT_MODE=multi`. |
+| `teamId` | **Soft scoping.** Stored on entries but not enforced by the server. Use application-layer filtering. |
+| `userId` | **Soft scoping.** Stored on entries but not enforced by the server. Use application-layer filtering. |
+| `agentId` | **Hard filtering.** When set in MemoryOptions or query params, only that agent's entries are returned. |
+
+**Key rule**: `TENANT_MODE=multi` enforces tenantId. userId and teamId are for your application to filter — pyx-memory stores them but does not enforce boundaries between users/teams within a tenant.
+
+---
+
+## Pattern 12: Sensitivity-Based Read Restriction
+
+Control which memories are visible based on the caller's access level. Entries classified above the caller's level are automatically redacted in search results.
+
+### How sensitivity classification works
+
+Every `store()` automatically scans content and classifies it:
+
+| Level | Auto-detected when | Example |
+|-------|-------------------|---------|
+| `public` | No credentials or PII detected | "Prefer tabs over spaces" |
+| `internal` | PII found (email, phone, SSN, etc.) | "Alice's email is alice@acme.com" |
+| `secret` | Credentials found (API keys, tokens, passwords) | "The API key is sk-ant-..." |
+
+### Restricting search results
+
+```typescript
+// Embedded: use maxSensitivity search param
+const results = await memory.search({
+  query: 'config',
+  maxSensitivity: 'internal', // only public + internal; secret entries are redacted
+});
+
+// Sidecar: use X-Caller-Access-Level header
+const restricted = new MemoryClient('http://memory:7822', {
+  apiKey: process.env.MEMORY_API_KEY,
+  defaultHeaders: {
+    'X-Caller-Access-Level': 'internal', // this client never sees secret entries
+  },
+});
+```
+
+### What "redacted" means
+
+When a search returns entries above the caller's access level, the content is replaced with `[REDACTED: sensitive content]`. The entry metadata (id, type, createdAt) is still visible so the caller knows something exists — they just can't read it.
+
+### Sensitivity policy options
+
+| `SENSITIVITY_POLICY` | Behavior |
+|----------------------|----------|
+| `flag` (default) | Classify and store sensitivity level. No content modification. |
+| `redact` | Replace detected credentials with `[REDACTED]` before storage. |
+| `block` | Reject any ingest containing credentials (HTTP 400). |
+| `encrypt` | Encrypt `secret` entries at rest with AES-256-GCM. Transparent decrypt on read when key is available. |
+
+```bash
+# Production config with encryption
+environment:
+  - SENSITIVITY_POLICY=encrypt
+  - ENCRYPTION_KEY=your-64-hex-char-key  # 32 bytes as hex
+```
+
+---
+
+## Pattern 13: Read-Only vs Read-Write Access
+
+pyx-memory has two auth tiers: `API_KEY` (read + write) and `ADMIN_API_KEY` (destructive ops). For finer read-only vs read-write control, use an API gateway or proxy layer in front.
+
+### Built-in auth tiers
+
+| Key | Allowed operations |
+|-----|-------------------|
+| `API_KEY` | All read operations (search, get, list, stats) + write operations (store, ingestFile) |
+| `ADMIN_API_KEY` | Destructive operations: DELETE, forget, decay, consolidate, reindex, deleteBySource |
+
+```bash
+# Give agents API_KEY (read + write), give admin tools ADMIN_API_KEY
+environment:
+  - API_KEY=agent-key-for-read-write
+  - ADMIN_API_KEY=admin-key-for-destructive-ops
+```
+
+### Adding read-only access via a proxy
+
+pyx-memory doesn't have a native "read-only API key." To implement read-only roles, put a reverse proxy (nginx, Caddy, API gateway) in front:
+
+```nginx
+# nginx example: read-only role blocks POST/PUT/DELETE
+location /api/memory/ {
+    # Read-only key can only GET
+    if ($http_authorization = "Bearer readonly-key") {
+        limit_except GET {
+            deny all;
+        }
+    }
+    proxy_pass http://memory:7822;
+}
+```
+
+Or implement it in your application layer:
+
+```typescript
+// Application-level access control middleware
+function memoryAccessMiddleware(req: Request, userRole: string): boolean {
+  const method = req.method;
+  const isWrite = method === 'POST' || method === 'PUT' || method === 'DELETE';
+
+  if (userRole === 'viewer' && isWrite) {
+    throw new ForbiddenError('Read-only access — cannot modify memory');
+  }
+  if (userRole === 'editor' && req.url.includes('/consolidate')) {
+    throw new ForbiddenError('Editors cannot run consolidation');
+  }
+  return true;
+}
+```
+
+---
+
+## Pattern 14: Full Production Stack
+
+Combines all patterns for a production multi-tenant deployment with sensitivity, encryption, and role-based access.
+
+### Server config
+
+```yaml
+# docker-compose.yaml
+services:
+  memory:
+    image: ghcr.io/pyx-corp/pyx-memory-v1:latest
+    environment:
+      - DATA_DIR=/data
+      - API_KEY=${MEMORY_API_KEY}
+      - ADMIN_API_KEY=${MEMORY_ADMIN_KEY}
+      - TENANT_MODE=multi
+      - SENSITIVITY_POLICY=encrypt
+      - ENCRYPTION_KEY=${ENCRYPTION_KEY}
+      - PII_POLICY=flag
+      - RATE_LIMIT_RPM=120
+      - CORS_ORIGIN=https://app.example.com
+      - NODE_ENV=production
+```
+
+### Client setup per role
+
+```typescript
+import { MemoryClient } from '@pyx-memory/client';
+
+const MEMORY_URL = 'http://memory:7822';
+
+// Admin client — full access, destructive ops allowed
+function createAdminClient(tenantId: string) {
+  return new MemoryClient(MEMORY_URL, {
+    apiKey: process.env.MEMORY_ADMIN_KEY,
+    defaultHeaders: {
+      'X-Tenant-Id': tenantId,
+      'X-Caller-Access-Level': 'secret',
+    },
+  });
+}
+
+// Agent client — read + write, scoped to agent + tenant
+function createAgentClient(tenantId: string, agentId: string) {
+  return new MemoryClient(MEMORY_URL, {
+    apiKey: process.env.MEMORY_API_KEY,
+    defaultHeaders: {
+      'X-Tenant-Id': tenantId,
+      'X-Caller-Access-Level': 'internal', // can't see secret entries
+    },
+  });
+  // Note: agentId is passed per-request, not via headers
+}
+
+// Dashboard client — read-only (enforce at application layer)
+function createDashboardClient(tenantId: string, userId: string) {
+  return new MemoryClient(MEMORY_URL, {
+    apiKey: process.env.MEMORY_API_KEY,
+    defaultHeaders: {
+      'X-Tenant-Id': tenantId,
+      'X-User-Id': userId,
+      'X-Caller-Access-Level': 'public', // most restricted view
+    },
+  });
+}
+```
+
+### What each role sees
+
+| Role | tenantId | agentId | maxSensitivity | Write | Delete/Admin |
+|------|----------|---------|----------------|-------|-------------|
+| Admin | scoped | all | secret | yes | yes (ADMIN_API_KEY) |
+| Agent | scoped | scoped | internal | yes | no |
+| Dashboard | scoped | all | public | no (app-enforced) | no |
+
+---
+
+## Architecture: Access Policy Layer
+
+For organizations that need true RBAC (role-based access control) with fine-grained per-entry permissions, the recommended architecture adds a policy layer between your application and pyx-memory:
+
+```
+User/Agent Request
+      ↓
+[Your Application]
+      ↓
+[Access Policy Layer]  ← checks role + scope before forwarding
+      ↓
+[pyx-memory]           ← stores data, unaware of permissions
+```
+
+### Why this is better than building ACL into the memory store
+
+1. **Separation of concerns** — memory stays fast and simple (store/retrieve). Access logic lives in your application where business rules belong.
+2. **Flexibility** — you can change access rules without migrating data or changing the memory schema.
+3. **Auditability** — policy decisions are logged at the application layer, not buried in storage internals.
+
+### Implementation approach
+
+```typescript
+// Define scopes as metadata on memory entries
+await memory.store({
+  content: 'Q4 revenue projections',
+  type: 'long-term',
+  metadata: {
+    scope: 'finance:confidential',       // your custom scope tag
+    allowedTeams: ['finance', 'exec'],   // who can read
+    allowedRoles: ['analyst', 'admin'],  // which roles
+  },
+});
+
+// In your API gateway, filter results based on caller identity
+function filterByAccess(entries: MemoryEntry[], caller: CallerIdentity): MemoryEntry[] {
+  return entries.filter(entry => {
+    const meta = entry.metadata;
+    if (!meta.allowedTeams) return true; // no restriction = public
+    return (
+      meta.allowedTeams.includes(caller.teamId) ||
+      meta.allowedRoles.includes(caller.role)
+    );
+  });
+}
+```
+
+This approach is not built into pyx-memory because access policies are inherently application-specific. The memory store provides the building blocks (tenant isolation, sensitivity classification, metadata storage) — your application composes them into the access model that fits your organization.