audrey 0.20.0 → 0.21.0

package/docs/ollama-local-agents.md

@@ -0,0 +1,128 @@
+# Audrey With Ollama Local Agents
+
+Ollama provides local model inference. Audrey provides long-term memory. Treat Audrey as the memory sidecar that your Ollama-backed agent calls through tools.
+
+This is intentionally host-neutral: the same Audrey data directory can be shared by Codex, Claude Code, Claude Desktop, and a local Ollama agent, or isolated per project.
+
+## Start Audrey
+
+```bash
+AUDREY_AGENT=ollama-local-agent AUDREY_EMBEDDING_PROVIDER=local npx audrey serve
+```
+
+Health check:
+
+```bash
+curl http://localhost:7437/health
+curl http://localhost:7437/v1/status
+```
+
+Use `AUDREY_API_KEY` if the sidecar is reachable beyond your local process boundary:
+
+```bash
+AUDREY_API_KEY=secret AUDREY_AGENT=ollama-local-agent npx audrey serve
+```
+
+## Memory Tools To Expose
+
+Expose these Audrey routes as function tools in your local agent loop:
+
+| Tool | Audrey route | Purpose |
+|---|---|---|
+| `memory_preflight` | `POST /v1/preflight` | Check known risks, rules, procedures, and prior failures before tool use |
+| `memory_reflexes` | `POST /v1/reflexes` | Convert preflight evidence into trigger-response rules the agent can automate |
+| `memory_capsule` | `POST /v1/capsule` | Build a compact, ranked context packet for the current task |
+| `memory_recall` | `POST /v1/recall` | Search durable memories |
+| `memory_encode` | `POST /v1/encode` | Store useful observations, decisions, procedures, and preferences |
+| `memory_status` | `GET /v1/status` | Check memory/index health |
+
+Minimum useful loop:
+
+1. Before tool use, call `memory_reflexes` or `memory_preflight` for the proposed action.
+2. If a reflex says `block`, stop and ask for repair or approval.
+3. Before calling Ollama, ask Audrey for a capsule using the user task as the query.
+4. Add the capsule to the model instructions or context.
+5. Let the model call `memory_recall` for details when needed.
+6. After the task, call `memory_encode` for durable facts, decisions, mistakes, procedures, and preferences.
+7. Run `npx audrey dream` on a schedule to consolidate and decay memory.
+
+## Native Ollama Tool Shape
+
+Ollama supports function tools on `/api/chat`. Your agent owns the loop that executes a tool call and sends the result back to the model.
+
+Audrey ships a complete example loop:
+
+```bash
+OLLAMA_MODEL=qwen3 node examples/ollama-memory-agent.js "What should you remember about this project?"
+```
+
+```json
+{
+  "type": "function",
+  "function": {
+    "name": "memory_recall",
+    "description": "Recall Audrey memories relevant to a query.",
+    "parameters": {
+      "type": "object",
+      "required": ["query"],
+      "properties": {
+        "query": {
+          "type": "string",
+          "description": "Search query for durable memory."
+        },
+        "limit": {
+          "type": "number",
+          "description": "Maximum results to return."
+        }
+      }
+    }
+  }
+}
+```
+
+Tool executor:
+
+```js
+export async function memoryRecall({ query, limit = 5 }) {
+  const response = await fetch('http://localhost:7437/v1/recall', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ query, limit }),
+  });
+  if (!response.ok) {
+    throw new Error(`Audrey recall failed: ${response.status}`);
+  }
+  return response.json();
+}
+```
+
+## OpenAI-Compatible Ollama Mode
+
+Ollama also exposes an OpenAI-compatible API at `http://localhost:11434/v1/`. If your local agent framework already knows how to call OpenAI-style tools, point the model client at Ollama and keep Audrey as the tool executor.
+
+The important separation is:
+
+- Ollama answers with local models.
+- Audrey remembers, recalls, reconciles, and consolidates.
+- The agent loop decides when a model tool call should hit Audrey.
+
+Official Ollama references:
+
+- Native tool calling: <https://docs.ollama.com/capabilities/tool-calling>
+- OpenAI-compatible API: <https://docs.ollama.com/openai>
+
+## Data Layout
+
+For shared memory across hosts:
+
+```bash
+AUDREY_DATA_DIR=$HOME/.audrey/data
+```
+
+For project-local memory:
+
+```bash
+AUDREY_DATA_DIR=.audrey-data
+```
+
+Shared memory is better for personal continuity across Codex, Claude, and local agents. Project-local memory is better when clients, repositories, or experiments must not bleed into each other.

package/docs/production-readiness.md

@@ -2,7 +2,7 @@
 
 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.
+First contact should now go through `npx audrey doctor`, then `npx audrey install --host <host> --dry-run` for local MCP hosts, `npx audrey install` for Claude Code specifically, or `npx audrey serve` for the sidecar path. Run `npx audrey status --json --fail-on-unhealthy` before exposing Audrey to real traffic.
 
 ## Best Vertical Fit
 
@@ -56,19 +56,24 @@ Guardrails:
 
 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`.
+3. Add a startup check that runs `npx audrey doctor --json`.
 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.
+8. Use `npx audrey install --host <host> --dry-run` in deployment docs so operators can preview host config without accidental writes.
+9. Keep API keys, bearer tokens, and raw credentials out of encoded memory content.
+10. Decide whether `private` memories are allowed for your use case and document who can create them.
+11. Add application-level encryption, access control, logging, and retention policies around Audrey.
+12. On graceful shutdown paths, call `await brain.waitForIdle()` before `brain.close()` so tracked background work drains cleanly.
 
 ## Operations Commands
 
 ```bash
+# First-contact diagnostics
+npx audrey doctor
+npx audrey doctor --json
+
 # Human-readable health
 npx audrey status
 
@@ -102,7 +107,6 @@ That keeps Audrey focused on memory integrity while the host system owns complia
 Audrey now ships with a first-party container path for the REST API:
 
 ```bash
-npx audrey init sidecar-prod
 docker compose up -d --build
 ```
 

package/examples/ollama-memory-agent.js

@@ -0,0 +1,326 @@
+#!/usr/bin/env node
+
+const AUDREY_URL = (process.env.AUDREY_URL || 'http://127.0.0.1:7437').replace(/\/$/, '');
+const OLLAMA_URL = (process.env.OLLAMA_URL || 'http://127.0.0.1:11434').replace(/\/$/, '');
+const OLLAMA_MODEL = process.env.OLLAMA_MODEL || 'qwen3';
+const AUDREY_API_KEY = process.env.AUDREY_API_KEY || '';
+const MAX_TOOL_LOOPS = Number.parseInt(process.env.MAX_TOOL_LOOPS || '4', 10);
+
+const userPrompt = process.argv.slice(2).join(' ').trim()
+  || 'Use Audrey memory to explain how this local Ollama agent should remember useful facts.';
+
+function usage() {
+  console.log(`
+Audrey + Ollama local memory agent
+
+Prerequisites:
+  1. Start Audrey: AUDREY_AGENT=ollama-local-agent npx audrey serve
+  2. Start Ollama and pull a tool-capable model: ollama pull qwen3
+
+Run:
+  OLLAMA_MODEL=qwen3 node examples/ollama-memory-agent.js "What should you remember about this project?"
+
+Environment:
+  AUDREY_URL=http://127.0.0.1:7437
+  AUDREY_API_KEY=secret
+  OLLAMA_URL=http://127.0.0.1:11434
+  OLLAMA_MODEL=qwen3
+`);
+}
+
+function headers() {
+  const h = { 'Content-Type': 'application/json' };
+  if (AUDREY_API_KEY) h.Authorization = `Bearer ${AUDREY_API_KEY}`;
+  return h;
+}
+
+async function jsonFetch(url, options = {}) {
+  const response = await fetch(url, options);
+  const text = await response.text();
+  let data = null;
+  if (text.trim()) {
+    try {
+      data = JSON.parse(text);
+    } catch {
+      data = { raw: text };
+    }
+  }
+  if (!response.ok) {
+    const detail = data?.error || data?.message || text || response.statusText;
+    throw new Error(`${response.status} ${response.statusText}: ${detail}`);
+  }
+  return data;
+}
+
+async function audreyGet(path) {
+  return jsonFetch(`${AUDREY_URL}${path}`, { headers: headers() });
+}
+
+async function audreyPost(path, body) {
+  return jsonFetch(`${AUDREY_URL}${path}`, {
+    method: 'POST',
+    headers: headers(),
+    body: JSON.stringify(body),
+  });
+}
+
+async function memoryRecall({ query, limit = 5 }) {
+  if (!query || typeof query !== 'string') {
+    throw new Error('memory_recall requires a string query');
+  }
+  return audreyPost('/v1/recall', { query, limit });
+}
+
+async function memoryCapsule({ query, budget_chars = 4000 }) {
+  if (!query || typeof query !== 'string') {
+    throw new Error('memory_capsule requires a string query');
+  }
+  return audreyPost('/v1/capsule', { query, budget_chars });
+}
+
+async function memoryPreflight({ action, tool, strict = false, include_capsule = false }) {
+  if (!action || typeof action !== 'string') {
+    throw new Error('memory_preflight requires a string action');
+  }
+  return audreyPost('/v1/preflight', { action, tool, strict, include_capsule });
+}
+
+async function memoryReflexes({ action, tool, strict = false, include_preflight = false }) {
+  if (!action || typeof action !== 'string') {
+    throw new Error('memory_reflexes requires a string action');
+  }
+  return audreyPost('/v1/reflexes', { action, tool, strict, include_preflight });
+}
+
+async function memoryEncode({ content, source = 'model-generated', tags = ['ollama-agent'] }) {
+  if (!content || typeof content !== 'string') {
+    throw new Error('memory_encode requires string content');
+  }
+  return audreyPost('/v1/encode', { content, source, tags });
+}
+
+const toolExecutors = {
+  memory_preflight: memoryPreflight,
+  memory_reflexes: memoryReflexes,
+  memory_recall: memoryRecall,
+  memory_capsule: memoryCapsule,
+  memory_encode: memoryEncode,
+};
+
+const tools = [
+  {
+    type: 'function',
+    function: {
+      name: 'memory_preflight',
+      description: 'Check Audrey memory before taking an action, so prior failures and rules are not repeated.',
+      parameters: {
+        type: 'object',
+        required: ['action'],
+        properties: {
+          action: { type: 'string', description: 'Action the agent is considering.' },
+          tool: { type: 'string', description: 'Optional tool or command family.' },
+          strict: { type: 'boolean', description: 'If true, high-severity warnings can block the action.' },
+          include_capsule: { type: 'boolean', description: 'Include full capsule context in the result.' },
+        },
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'memory_reflexes',
+      description: 'Return Audrey Memory Reflexes: trigger-response rules for the action the agent is considering.',
+      parameters: {
+        type: 'object',
+        required: ['action'],
+        properties: {
+          action: { type: 'string', description: 'Action the agent is considering.' },
+          tool: { type: 'string', description: 'Optional tool or command family.' },
+          strict: { type: 'boolean', description: 'If true, high-severity warnings can become blocking reflexes.' },
+          include_preflight: { type: 'boolean', description: 'Include the full underlying preflight report.' },
+        },
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'memory_recall',
+      description: 'Recall durable Audrey memories relevant to a query.',
+      parameters: {
+        type: 'object',
+        required: ['query'],
+        properties: {
+          query: { type: 'string', description: 'Search query for Audrey memory.' },
+          limit: { type: 'number', description: 'Maximum memories to return.' },
+        },
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'memory_capsule',
+      description: 'Build a compact, evidence-backed Audrey Memory Capsule for the current task.',
+      parameters: {
+        type: 'object',
+        required: ['query'],
+        properties: {
+          query: { type: 'string', description: 'Current task or question.' },
+          budget_chars: { type: 'number', description: 'Maximum capsule size in characters.' },
+        },
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'memory_encode',
+      description: 'Store a useful lasting observation, decision, preference, or procedure in Audrey.',
+      parameters: {
+        type: 'object',
+        required: ['content'],
+        properties: {
+          content: { type: 'string', description: 'Memory content to store.' },
+          source: {
+            type: 'string',
+            enum: ['direct-observation', 'told-by-user', 'tool-result', 'inference', 'model-generated'],
+            description: 'Source reliability category.',
+          },
+          tags: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Searchable tags for this memory.',
+          },
+        },
+      },
+    },
+  },
+];
+
+function parseToolArguments(args) {
+  if (args == null) return {};
+  if (typeof args === 'string') {
+    try {
+      return JSON.parse(args);
+    } catch {
+      return { raw: args };
+    }
+  }
+  return args;
+}
+
+async function ollamaChat(messages) {
+  return jsonFetch(`${OLLAMA_URL}/api/chat`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      model: OLLAMA_MODEL,
+      stream: false,
+      messages,
+      tools,
+    }),
+  });
+}
+
+async function main() {
+  if (process.argv.includes('--help') || process.argv.includes('-h')) {
+    usage();
+    return;
+  }
+
+  try {
+    await audreyGet('/health');
+  } catch (err) {
+    console.error(`Audrey is not reachable at ${AUDREY_URL}.`);
+    console.error('Start it with: AUDREY_AGENT=ollama-local-agent npx audrey serve');
+    console.error(`Details: ${err.message}`);
+    process.exit(1);
+  }
+
+  const reflexes = await memoryReflexes({ action: userPrompt, include_preflight: false });
+  const preflight = await memoryPreflight({ action: userPrompt, include_capsule: false });
+  const capsule = await memoryCapsule({ query: userPrompt, budget_chars: 4000 });
+  const messages = [
+    {
+      role: 'system',
+      content: [
+        'You are a local Ollama agent with Audrey long-term memory.',
+        'Use Audrey tools when memory would improve the answer.',
+        'Before taking risky tool actions, call memory_reflexes or memory_preflight and follow any warnings.',
+        'Store only durable preferences, facts, decisions, procedures, and useful lessons.',
+        '',
+        'Initial Audrey Memory Reflexes:',
+        JSON.stringify(reflexes, null, 2).slice(0, 3000),
+        '',
+        'Initial Audrey Preflight:',
+        JSON.stringify(preflight, null, 2).slice(0, 3000),
+        '',
+        'Initial Audrey Memory Capsule:',
+        JSON.stringify(capsule, null, 2).slice(0, 6000),
+      ].join('\n'),
+    },
+    { role: 'user', content: userPrompt },
+  ];
+
+  console.error(`[audrey-ollama] model=${OLLAMA_MODEL} audrey=${AUDREY_URL} ollama=${OLLAMA_URL}`);
+
+  for (let i = 0; i < MAX_TOOL_LOOPS; i += 1) {
+    let response;
+    try {
+      response = await ollamaChat(messages);
+    } catch (err) {
+      console.error(`Ollama is not reachable at ${OLLAMA_URL}, or model "${OLLAMA_MODEL}" is not available.`);
+      console.error(`Try: ollama pull ${OLLAMA_MODEL}`);
+      console.error(`Details: ${err.message}`);
+      process.exit(1);
+    }
+
+    const message = response.message || {};
+    messages.push(message);
+
+    const calls = message.tool_calls || [];
+    if (calls.length === 0) {
+      console.log(message.content || '(model returned no content)');
+      await memoryEncode({
+        content: `Ollama agent answered: ${userPrompt.slice(0, 240)}`,
+        source: 'model-generated',
+        tags: ['ollama-agent', 'session-summary'],
+      }).catch(() => undefined);
+      return;
+    }
+
+    for (const call of calls) {
+      const name = call.function?.name;
+      const executor = toolExecutors[name];
+      if (!executor) {
+        messages.push({ role: 'tool', tool_name: name || 'unknown', content: 'Unknown Audrey tool' });
+        continue;
+      }
+
+      const args = parseToolArguments(call.function?.arguments);
+      console.error(`[audrey-ollama] tool ${name} ${JSON.stringify(args)}`);
+      try {
+        const result = await executor(args);
+        messages.push({
+          role: 'tool',
+          tool_name: name,
+          content: JSON.stringify(result).slice(0, 8000),
+        });
+      } catch (err) {
+        messages.push({
+          role: 'tool',
+          tool_name: name,
+          content: `Audrey tool error: ${err.message}`,
+        });
+      }
+    }
+  }
+
+  console.log('Stopped after MAX_TOOL_LOOPS without a final model answer.');
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "audrey",
-  "version": "0.20.0",
-  "description": "Biological memory architecture for AI agents - encode, consolidate, and recall memories with confidence decay, contradiction detection, and causal graphs",
+  "version": "0.21.0",
+  "description": "Local-first memory runtime for AI agents with recall, consolidation, memory reflexes, contradiction detection, and tool-trace learning",
   "type": "module",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
@@ -27,8 +27,16 @@
     "dist/",
     "docs/production-readiness.md",
     "docs/benchmarking.md",
+    "docs/audrey-for-dummies.md",
+    "docs/future-of-llm-memory.md",
+    "docs/mcp-hosts.md",
+    "docs/ollama-local-agents.md",
+    "docs/assets/audrey-feature-grid.jpg",
+    "docs/assets/audrey-logo.svg",
+    "docs/assets/audrey-wordmark.png",
     "docs/assets/benchmarks/",
     "examples/",
+    "CHANGELOG.md",
     "README.md",
     "LICENSE"
   ],
@@ -76,6 +84,12 @@
     "confidence",
     "long-term-memory",
     "persistent-memory",
+    "memory-preflight",
+    "memory-reflexes",
+    "agent-reflexes",
+    "agent-safety",
+    "tool-trace-memory",
+    "local-first-memory",
     "rag",
     "claude",
     "agent-framework",
@@ -112,5 +126,10 @@
     "@types/node": "^25.6.0",
     "typescript": "^6.0.2",
     "vitest": "^4.0.18"
+  },
+  "directories": {
+    "doc": "docs",
+    "example": "examples",
+    "test": "tests"
   }
 }