audrey 0.16.1 → 0.20.0

package/dist/src/validate.js

@@ -0,0 +1,109 @@
+import { generateId } from './ulid.js';
+import { safeJsonParse } from './utils.js';
+import { buildContradictionDetectionPrompt } from './prompts.js';
+const REINFORCEMENT_THRESHOLD = 0.85;
+const CONTRADICTION_THRESHOLD = 0.60;
+export async function validateMemory(db, embeddingProvider, episode, options = {}) {
+    const { threshold = REINFORCEMENT_THRESHOLD, contradictionThreshold = CONTRADICTION_THRESHOLD, llmProvider, } = options;
+    const episodeVector = await embeddingProvider.embed(episode.content);
+    const episodeBuffer = embeddingProvider.vectorToBuffer(episodeVector);
+    const nearestSemantic = db.prepare(`
+    SELECT s.*, (1.0 - v.distance) AS similarity
+    FROM vec_semantics v
+    JOIN semantics s ON s.id = v.id
+    WHERE v.embedding MATCH ?
+      AND k = 1
+      AND (v.state = 'active' OR v.state = 'context_dependent')
+  `).get(episodeBuffer);
+    let bestMatch = null;
+    let bestSimilarity = 0;
+    if (nearestSemantic) {
+        bestMatch = nearestSemantic;
+        bestSimilarity = nearestSemantic.similarity;
+    }
+    if (bestMatch && bestSimilarity >= threshold) {
+        const evidenceIds = safeJsonParse(bestMatch.evidence_episode_ids, []);
+        if (!evidenceIds.includes(episode.id)) {
+            evidenceIds.push(episode.id);
+        }
+        const diversity = computeSourceDiversity(db, evidenceIds, episode);
+        const now = new Date().toISOString();
+        db.prepare(`
+      UPDATE semantics SET
+        supporting_count = supporting_count + 1,
+        evidence_episode_ids = ?,
+        evidence_count = ?,
+        source_type_diversity = ?,
+        last_reinforced_at = ?
+      WHERE id = ?
+    `).run(JSON.stringify(evidenceIds), evidenceIds.length, diversity, now, bestMatch.id);
+        return {
+            action: 'reinforced',
+            semanticId: bestMatch.id,
+            similarity: bestSimilarity,
+        };
+    }
+    if (bestMatch && bestSimilarity >= contradictionThreshold && llmProvider) {
+        const messages = buildContradictionDetectionPrompt(episode.content, bestMatch.content);
+        const verdict = await llmProvider.json(messages);
+        if (verdict.contradicts) {
+            const resolution = verdict.resolution === 'context_dependent'
+                ? { type: 'context_dependent', conditions: verdict.conditions, explanation: verdict.explanation }
+                : verdict.resolution
+                    ? { type: verdict.resolution, explanation: verdict.explanation }
+                    : null;
+            const contradictionId = createContradiction(db, bestMatch.id, 'semantic', episode.id, 'episodic', resolution);
+            if (verdict.resolution === 'new_wins') {
+                db.prepare("UPDATE semantics SET state = 'disputed' WHERE id = ?").run(bestMatch.id);
+            }
+            else if (verdict.resolution === 'context_dependent' && verdict.conditions) {
+                db.prepare("UPDATE semantics SET state = 'context_dependent', conditions = ? WHERE id = ?")
+                    .run(JSON.stringify(verdict.conditions), bestMatch.id);
+            }
+            return {
+                action: 'contradiction',
+                contradictionId,
+                semanticId: bestMatch.id,
+                similarity: bestSimilarity,
+                resolution: verdict.resolution || null,
+            };
+        }
+    }
+    return { action: 'none' };
+}
+function computeSourceDiversity(db, evidenceIds, currentEpisode) {
+    const sourceTypes = new Set();
+    sourceTypes.add(currentEpisode.source);
+    if (evidenceIds.length > 0) {
+        const placeholders = evidenceIds.map(() => '?').join(',');
+        const rows = db.prepare(`SELECT DISTINCT source FROM episodes WHERE id IN (${placeholders})`).all(...evidenceIds);
+        for (const row of rows) {
+            sourceTypes.add(row.source);
+        }
+    }
+    return sourceTypes.size;
+}
+export function createContradiction(db, claimAId, claimAType, claimBId, claimBType, resolution) {
+    const id = generateId();
+    const now = new Date().toISOString();
+    const state = resolution ? 'resolved' : 'open';
+    const resolvedAt = resolution ? now : null;
+    const resolutionJson = resolution ? JSON.stringify(resolution) : null;
+    db.prepare(`
+    INSERT INTO contradictions (id, claim_a_id, claim_a_type, claim_b_id, claim_b_type,
+      state, resolution, resolved_at, created_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(id, claimAId, claimAType, claimBId, claimBType, state, resolutionJson, resolvedAt, now);
+    return id;
+}
+export function reopenContradiction(db, contradictionId, newEvidenceId) {
+    const now = new Date().toISOString();
+    db.prepare(`
+    UPDATE contradictions SET
+      state = 'reopened',
+      reopen_evidence_id = ?,
+      reopened_at = ?
+    WHERE id = ?
+  `).run(newEvidenceId, now, contradictionId);
+}
+//# sourceMappingURL=validate.js.map

package/dist/src/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../src/validate.ts"],"names":[],"mappings":"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"}

package/docs/assets/benchmarks/local-benchmark.svg

@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="960" height="420" viewBox="0 0 960 420" role="img" aria-label="Audrey vs Local Memory Baselines">
+  <rect width="100%" height="100%" fill="white" />
+  <text x="64" y="34" font-size="24" font-weight="700" fill="#111827">Audrey vs Local Memory Baselines</text>
+  
+      <line x1="64" y1="332" x2="928" y2="332" stroke="#cbd5e1" stroke-dasharray="4 4" />
+      <text x="54" y="337" text-anchor="end" font-size="13" fill="#6b7280">0%</text>
+    
+
+      <line x1="64" y1="263" x2="928" y2="263" stroke="#cbd5e1" stroke-dasharray="4 4" />
+      <text x="54" y="268" text-anchor="end" font-size="13" fill="#6b7280">25%</text>
+    
+
+      <line x1="64" y1="194" x2="928" y2="194" stroke="#cbd5e1" stroke-dasharray="4 4" />
+      <text x="54" y="199" text-anchor="end" font-size="13" fill="#6b7280">50%</text>
+    
+
+      <line x1="64" y1="125" x2="928" y2="125" stroke="#cbd5e1" stroke-dasharray="4 4" />
+      <text x="54" y="130" text-anchor="end" font-size="13" fill="#6b7280">75%</text>
+    
+
+      <line x1="64" y1="56" x2="928" y2="56" stroke="#cbd5e1" stroke-dasharray="4 4" />
+      <text x="54" y="61" text-anchor="end" font-size="13" fill="#6b7280">100%</text>
+    
+  
+      <rect x="64" y="56" width="198" height="276" rx="8" fill="#0f766e" />
+      <text x="163" y="46" text-anchor="middle" font-size="15" fill="#111827">100.0%</text>
+      <text x="163" y="378" text-anchor="middle" font-size="14" fill="#6b7280">Audrey</text>
+    
+
+      <rect x="286" y="217" width="198" height="115.00000000000001" rx="8" fill="#0369a1" />
+      <text x="385" y="207" text-anchor="middle" font-size="15" fill="#111827">41.7%</text>
+      <text x="385" y="378" text-anchor="middle" font-size="14" fill="#6b7280">Vector Only</text>
+    
+
+      <rect x="508" y="217" width="198" height="115.00000000000001" rx="8" fill="#6d28d9" />
+      <text x="607" y="207" text-anchor="middle" font-size="15" fill="#111827">41.7%</text>
+      <text x="607" y="378" text-anchor="middle" font-size="14" fill="#6b7280">Keyword + Recency</text>
+    
+
+      <rect x="730" y="228.5" width="198" height="103.5" rx="8" fill="#b45309" />
+      <text x="829" y="218.5" text-anchor="middle" font-size="15" fill="#111827">37.5%</text>
+      <text x="829" y="378" text-anchor="middle" font-size="14" fill="#6b7280">Recent Window</text>
+    
+</svg>

package/docs/assets/benchmarks/operations-benchmark.svg

@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="960" height="420" viewBox="0 0 960 420" role="img" aria-label="Audrey Memory Operations Benchmark">
+  <rect width="100%" height="100%" fill="white" />
+  <text x="64" y="34" font-size="24" font-weight="700" fill="#111827">Audrey Memory Operations Benchmark</text>
+  
+      <line x1="64" y1="332" x2="928" y2="332" stroke="#cbd5e1" stroke-dasharray="4 4" />
+      <text x="54" y="337" text-anchor="end" font-size="13" fill="#6b7280">0%</text>
+    
+
+      <line x1="64" y1="263" x2="928" y2="263" stroke="#cbd5e1" stroke-dasharray="4 4" />
+      <text x="54" y="268" text-anchor="end" font-size="13" fill="#6b7280">25%</text>
+    
+
+      <line x1="64" y1="194" x2="928" y2="194" stroke="#cbd5e1" stroke-dasharray="4 4" />
+      <text x="54" y="199" text-anchor="end" font-size="13" fill="#6b7280">50%</text>
+    
+
+      <line x1="64" y1="125" x2="928" y2="125" stroke="#cbd5e1" stroke-dasharray="4 4" />
+      <text x="54" y="130" text-anchor="end" font-size="13" fill="#6b7280">75%</text>
+    
+
+      <line x1="64" y1="56" x2="928" y2="56" stroke="#cbd5e1" stroke-dasharray="4 4" />
+      <text x="54" y="61" text-anchor="end" font-size="13" fill="#6b7280">100%</text>
+    
+  
+      <rect x="64" y="56" width="198" height="276" rx="8" fill="#0f766e" />
+      <text x="163" y="46" text-anchor="middle" font-size="15" fill="#111827">100.0%</text>
+      <text x="163" y="378" text-anchor="middle" font-size="14" fill="#6b7280">Audrey</text>
+    
+
+      <rect x="286" y="263" width="198" height="69" rx="8" fill="#6d28d9" />
+      <text x="385" y="253" text-anchor="middle" font-size="15" fill="#111827">25.0%</text>
+      <text x="385" y="378" text-anchor="middle" font-size="14" fill="#6b7280">Keyword + Recency</text>
+    
+
+      <rect x="508" y="297.5" width="198" height="34.5" rx="8" fill="#0369a1" />
+      <text x="607" y="287.5" text-anchor="middle" font-size="15" fill="#111827">12.5%</text>
+      <text x="607" y="378" text-anchor="middle" font-size="14" fill="#6b7280">Vector Only</text>
+    
+
+      <rect x="730" y="297.5" width="198" height="34.5" rx="8" fill="#b45309" />
+      <text x="829" y="287.5" text-anchor="middle" font-size="15" fill="#111827">12.5%</text>
+      <text x="829" y="378" text-anchor="middle" font-size="14" fill="#6b7280">Recent Window</text>
+    
+</svg>

package/docs/assets/benchmarks/published-memory-standards.svg

@@ -0,0 +1,50 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="960" height="420" viewBox="0 0 960 420" role="img" aria-label="Published LLM Memory Standards (LoCoMo)">
+  <rect width="100%" height="100%" fill="white" />
+  <text x="64" y="34" font-size="24" font-weight="700" fill="#111827">Published LLM Memory Standards (LoCoMo)</text>
+  
+      <line x1="64" y1="332" x2="928" y2="332" stroke="#cbd5e1" stroke-dasharray="4 4" />
+      <text x="54" y="337" text-anchor="end" font-size="13" fill="#6b7280">0%</text>
+    
+
+      <line x1="64" y1="263" x2="928" y2="263" stroke="#cbd5e1" stroke-dasharray="4 4" />
+      <text x="54" y="268" text-anchor="end" font-size="13" fill="#6b7280">25%</text>
+    
+
+      <line x1="64" y1="194" x2="928" y2="194" stroke="#cbd5e1" stroke-dasharray="4 4" />
+      <text x="54" y="199" text-anchor="end" font-size="13" fill="#6b7280">50%</text>
+    
+
+      <line x1="64" y1="125" x2="928" y2="125" stroke="#cbd5e1" stroke-dasharray="4 4" />
+      <text x="54" y="130" text-anchor="end" font-size="13" fill="#6b7280">75%</text>
+    
+
+      <line x1="64" y1="56" x2="928" y2="56" stroke="#cbd5e1" stroke-dasharray="4 4" />
+      <text x="54" y="61" text-anchor="end" font-size="13" fill="#6b7280">100%</text>
+    
+  
+      <rect x="64" y="96.29599999999996" width="154" height="235.70400000000004" rx="8" fill="#1d4ed8" />
+      <text x="141" y="86.29599999999996" text-anchor="middle" font-size="15" fill="#111827">85.4%</text>
+      <text x="141" y="378" text-anchor="middle" font-size="14" fill="#6b7280">MIRIX</text>
+    
+
+      <rect x="241.5" y="127.75999999999999" width="154" height="204.24" rx="8" fill="#1d4ed8" />
+      <text x="318.5" y="117.75999999999999" text-anchor="middle" font-size="15" fill="#111827">74.0%</text>
+      <text x="318.5" y="378" text-anchor="middle" font-size="14" fill="#6b7280">Letta Filesystem</text>
+    
+
+      <rect x="419" y="142.94" width="154" height="189.06" rx="8" fill="#1d4ed8" />
+      <text x="496" y="132.94" text-anchor="middle" font-size="15" fill="#111827">68.5%</text>
+      <text x="496" y="378" text-anchor="middle" font-size="14" fill="#6b7280">Mem0 Graph Memory</text>
+    
+
+      <rect x="596.5" y="147.356" width="154" height="184.644" rx="8" fill="#1d4ed8" />
+      <text x="673.5" y="137.356" text-anchor="middle" font-size="15" fill="#111827">66.9%</text>
+      <text x="673.5" y="378" text-anchor="middle" font-size="14" fill="#6b7280">Mem0</text>
+    
+
+      <rect x="774" y="185.99599999999998" width="154" height="146.00400000000002" rx="8" fill="#1d4ed8" />
+      <text x="851" y="175.99599999999998" text-anchor="middle" font-size="15" fill="#111827">52.9%</text>
+      <text x="851" y="378" text-anchor="middle" font-size="14" fill="#6b7280">OpenAI Memory</text>
+    
+</svg>

package/docs/benchmarking.md

@@ -0,0 +1,151 @@
+# Benchmarking Audrey
+
+Audrey now ships with a memory benchmark harness that does three different jobs:
+
+1. It runs Audrey against a local retrieval suite inspired by LongMemEval, plus privacy and abstention checks that matter in production.
+2. It runs Audrey against an operation-level suite for update, overwrite, delete, merge, and abstain behavior.
+3. It overlays published leaderboard numbers from leading memory systems on LoCoMo so you can place Audrey in the current market and research landscape without pretending the measurements are identical.
+
+That split is deliberate. A lot of memory tooling mixes internal demos with external benchmark claims. Audrey should not do that.
+
+## Run It
+
+```bash
+npm run bench:memory
+```
+
+The package script is the intended operator entrypoint:
+
+```bash
+npm run bench:memory
+```
+
+Artifacts are written to `benchmarks/output/`:
+
+- `summary.json`
+- `report.html`
+- `local-overall.svg`
+- `retrieval-overall.svg`
+- `operations-overall.svg`
+- `published-locomo.svg`
+
+For CI, JSON-only output is available:
+
+```bash
+npm run bench:memory:json
+```
+
+For regression gating, use:
+
+```bash
+npm run bench:memory:check
+```
+
+That command fails if Audrey falls below its minimum local score, pass rate, or required lead over the strongest naive baseline.
+
+To refresh the committed SVGs used in the README:
+
+```bash
+npm run bench:memory:readme-assets
+```
+
+That writes stable chart assets to `docs/assets/benchmarks/` so the GitHub repo surface shows the same benchmark posture as the generated report.
+
+To run a single local track:
+
+```bash
+npm run bench:memory:retrieval
+npm run bench:memory:operations
+```
+
+## What The Local Retrieval Benchmark Measures
+
+The retrieval suite covers eight memory families:
+
+- `information_extraction`
+- `knowledge_updates`
+- `multi_session_reasoning`
+- `temporal_reasoning`
+- `abstention`
+- `conflict_resolution`
+- `procedural_learning`
+- `privacy_boundary`
+
+This is intentionally closer to how operators evaluate memory in production than a single retrieval-accuracy number. Audrey should not only retrieve facts. It should:
+
+- prefer fresh state over stale state
+- avoid leaking private memory
+- consolidate repeated episodes into reusable procedures
+- handle conflict without amplifying low-reliability noise
+
+## What The Local Operations Benchmark Measures
+
+The operations suite covers four lifecycle families:
+
+- `update_overwrite`
+- `delete_and_abstain`
+- `semantic_merge`
+- `procedural_merge`
+
+This suite exists because leading memory systems are often compared on offline recall, while real agent memory succeeds or fails on memory operations:
+
+- can a newer fact overwrite stale state without leaking both
+- can a delete actually prevent future recall
+- can repeated raw events merge into reusable semantic knowledge
+- can repeated events merge into an actionable procedure instead of another inert blob of text
+
+Those are not implementation details. They are the actual product surface of memory.
+
+## What The Published Leaderboard Means
+
+The LoCoMo chart in the generated report is a research context layer, not a claim that Audrey has already reproduced those exact scores.
+
+Current published anchors included in the report:
+
+- MIRIX: LoCoMo `85.4` from the MIRIX paper
+- Letta Filesystem: LoCoMo `74.0` from Letta's benchmark write-up
+- Mem0 Graph Memory: LoCoMo `68.5` from the Mem0 paper
+- Mem0: LoCoMo `66.9` from the Mem0 paper
+- OpenAI Memory baseline: LoCoMo `52.9` as reported in the Mem0 paper
+
+Use this chart to answer: "Where is the frontier today?" not "Has Audrey already matched that exact benchmark protocol?"
+
+## March 23, 2026 Research Readout
+
+The most important memory trends right now:
+
+1. Typed memory systems are replacing flat retrieval.
+   MemOS frames memory as an operating system concern with scheduling and memory-object abstractions, not just vector lookup.
+
+2. Realistic long-horizon benchmarks are replacing toy recall tests.
+   LongMemEval emphasizes multi-session reasoning, temporal updates, abstraction, and knowledge revision.
+
+3. Context engineering is now a first-class competitor to retrieval-only memory.
+   Letta's filesystem and memory-block work argues that editable context structure can outperform simpler retrieval-only designs.
+
+4. Production memory is now judged on latency and token cost too.
+   Mem0 explicitly reports quality alongside lower token and latency overhead.
+
+5. Temporal and multimodal memory are moving into the frontier.
+   MIRIX pushes beyond text-only episodic recall into typed multimodal memory with compression.
+
+## What Audrey Should Do Next
+
+The benchmark highlights the next credible roadmap for Audrey:
+
+- first-party LoCoMo and LongMemEval adapters so Audrey can publish directly reproducible external benchmark numbers
+- contradiction-state and truth-resolution benchmark cases, not just retrieval outcomes
+- cost, latency, and storage curves against long-context baselines and simpler memory systems
+- a typed memory graph layer for cross-memory state transitions and time-aware reasoning
+
+## Source Links
+
+- LongMemEval: [arXiv 2410.10813](https://arxiv.org/abs/2410.10813)
+- Mem0: [arXiv 2504.19413](https://arxiv.org/abs/2504.19413)
+- MIRIX: [arXiv 2507.07957](https://arxiv.org/abs/2507.07957)
+- MemOS: [arXiv 2507.03724](https://arxiv.org/abs/2507.03724)
+- MemGPT: [arXiv 2310.08560](https://arxiv.org/abs/2310.08560)
+- Letta memory blocks: [Letta blog](https://www.letta.com/blog/memory-blocks)
+- Letta benchmarking: [Letta benchmark write-up](https://www.letta.com/blog/benchmarking-ai-agent-memory)
+- LoCoMo benchmark repo: [snap-research/locomo](https://github.com/snap-research/locomo)
+- LongMemEval repo: [xiaowu0162/LongMemEval](https://github.com/xiaowu0162/LongMemEval)

package/docs/production-readiness.md

@@ -0,0 +1,124 @@
+# Audrey Production Readiness
+
+Audrey is ready to be the memory layer inside a production agent system, but it is not a complete regulated-platform package by itself. Treat it as stateful infrastructure: pin providers, isolate tenants, monitor health, and wrap it with the controls your environment requires.
+
+First contact should now go through `npx audrey init sidecar-prod` for the sidecar path or `npx audrey init` for the default Claude Code path, then `npx audrey doctor` before exposing Audrey to real traffic.
+
+## Best Vertical Fit
+
+### 1. Financial Services Operations
+
+Best fit:
+
+- Payments operations copilots
+- Fraud and dispute investigation agents
+- KYC/KYB review assistants
+- Internal support agents that need durable incident and policy memory
+
+Why Audrey fits:
+
+- Contradiction tracking helps surface conflicting customer, tool, and policy evidence.
+- Confidence scoring and source lineage make escalations more reviewable.
+- Local SQLite storage keeps memory close to the application boundary.
+- Dream-cycle consolidation turns repeated incidents into reusable operational principles.
+
+Guardrails:
+
+- Do not store PAN, CVV, raw bank credentials, or secrets in memory.
+- Isolate memory stores by environment, customer, and business unit.
+- Keep export and purge paths in your incident-response runbook.
+- Add encryption at rest and backup retention outside Audrey.
+
+### 2. Healthcare Operations
+
+Best fit:
+
+- Care coordination assistants
+- Prior-authorization workflow agents
+- Intake, referral, and scheduling copilots
+- Internal knowledge assistants for clinical operations teams
+
+Why Audrey fits:
+
+- Longitudinal recall preserves operational context across multi-step handoffs.
+- Private memories support role-specific context without making it part of public recall.
+- Contradiction detection helps catch conflicting workflow instructions and stale operating assumptions.
+- Local embeddings allow offline-first or reduced-data-egress deployments.
+
+Guardrails:
+
+- Audrey is not a medical device and should not be treated as a clinical decision engine.
+- Use de-identified or minimum-necessary data unless the full deployment boundary is HIPAA-ready.
+- Enforce access controls and audit logging in the host application, not just in Audrey.
+- Separate patient-facing and staff-only memory scopes.
+
+## Production Checklist
+
+1. Pin `AUDREY_EMBEDDING_PROVIDER` and `AUDREY_LLM_PROVIDER` explicitly. Do not rely on key-based auto-detection in production.
+2. Set a dedicated `AUDREY_DATA_DIR` per environment and per tenant boundary.
+3. Add a health check that runs `npx audrey status --json --fail-on-unhealthy`.
+4. Alert on `health.healthy=false` or `health.reembed_recommended=true`.
+5. Schedule `npx audrey dream` during low-traffic windows so consolidation and decay stay current.
+6. Backup the SQLite data directory before changing embedding dimensions or providers.
+7. Treat re-embedding as a controlled maintenance action and validate with `npx audrey status`.
+8. Keep API keys, bearer tokens, and raw credentials out of encoded memory content.
+9. Decide whether `private` memories are allowed for your use case and document who can create them.
+10. Add application-level encryption, access control, logging, and retention policies around Audrey.
+11. On graceful shutdown paths, call `await brain.waitForIdle()` before `brain.close()` so tracked background work drains cleanly.
+
+## Operations Commands
+
+```bash
+# Human-readable health
+npx audrey status
+
+# Monitoring-friendly health
+npx audrey status --json
+
+# Fail the process if the index is unhealthy or unreadable
+npx audrey status --json --fail-on-unhealthy
+
+# Nightly memory maintenance
+npx audrey dream
+
+# Repair vector/index drift after provider or dimension changes
+npx audrey reembed
+```
+
+## Example Deployment Pattern
+
+Use Audrey as a local sidecar to the agent service:
+
+- One Audrey data directory per tenant or deployment shard
+- Health checks wired to `status --json`
+- Scheduled dream/reembed jobs
+- Backups handled by the host platform
+- Regulated-data filtering handled before `memory_encode`
+
+That keeps Audrey focused on memory integrity while the host system owns compliance, tenancy, and transport security.
+
+## Docker Deployment
+
+Audrey now ships with a first-party container path for the REST API:
+
+```bash
+npx audrey init sidecar-prod
+docker compose up -d --build
+```
+
+Operational notes:
+
+- The container persists SQLite data in the named volume `audrey-data`.
+- Set `AUDREY_API_KEY` before exposing the service beyond localhost.
+- For CI or very fast smoke checks, prefer `AUDREY_EMBEDDING_PROVIDER=mock` and `AUDREY_LLM_PROVIDER=mock`.
+- For stable local/offline container use, keep `AUDREY_EMBEDDING_PROVIDER=local` and `AUDREY_DEVICE=cpu`.
+- If you map the service to a different host port, keep the container port at `3487`.
+
+Suggested smoke check:
+
+```bash
+AUDREY_API_KEY=secret docker compose up -d --build
+curl -H "Authorization: Bearer secret" http://localhost:3487/health
+curl -H "Authorization: Bearer secret" http://localhost:3487/status
+docker compose logs --tail=100 audrey
+```

package/examples/fintech-ops-demo.js

@@ -0,0 +1,67 @@
+import { Audrey } from '../dist/src/index.js';
+
+async function demo() {
+  console.log('=== Audrey Demo: Financial Services Operations ===\n');
+
+  const brain = new Audrey({
+    dataDir: './fintech-demo-data',
+    agent: 'payments-ops-agent',
+    embedding: { provider: 'mock', dimensions: 64 },
+  });
+
+  console.log('--- Encoding payment-operations incidents ---');
+  await brain.encode({
+    content: 'Processor X returned HTTP 429 when payout retries exceeded 120 requests per minute for marketplace merchants.',
+    source: 'direct-observation',
+    salience: 0.9,
+    tags: ['payments', 'payouts', 'rate-limit'],
+    context: { domain: 'finserv', workflow: 'payout-incident' },
+  });
+
+  await brain.encode({
+    content: 'On-call notes show payout incident volume drops after retry batches are capped at 50 merchants per worker.',
+    source: 'tool-result',
+    salience: 0.8,
+    tags: ['payments', 'payouts', 'ops'],
+    context: { domain: 'finserv', workflow: 'payout-incident' },
+  });
+
+  await brain.encode({
+    content: 'Risk operations requested automatic escalation when payout failures affect more than three merchants in the same hour.',
+    source: 'told-by-user',
+    salience: 0.7,
+    tags: ['payments', 'escalation', 'risk'],
+    context: { domain: 'finserv', workflow: 'payout-incident' },
+  });
+
+  console.log('\n--- Consolidating incidents into an ops principle ---');
+  await brain.consolidate({
+    minClusterSize: 3,
+    similarityThreshold: -0.3,
+    extractPrinciple: () => ({
+      content: 'When payout retries spike, cap retry batches and escalate once multiple merchants are affected in the same hour.',
+      type: 'procedural',
+      conditions: ['payout failures > 3 merchants per hour', 'processor returns 429 or throttling errors'],
+    }),
+  });
+
+  console.log('\n--- Recalling during a live payout incident ---');
+  const recalled = await brain.recall('payout retries throttled by processor', {
+    limit: 5,
+    context: { domain: 'finserv', workflow: 'payout-incident' },
+  });
+
+  for (const memory of recalled) {
+    console.log(`[${memory.type}] ${memory.content}`);
+  }
+
+  brain.close();
+
+  const { rmSync } = await import('node:fs');
+  rmSync('./fintech-demo-data', { recursive: true, force: true });
+}
+
+demo().catch(err => {
+  console.error(err);
+  process.exit(1);
+});