audrey 0.17.0 → 0.20.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (191) hide show
  1. package/README.md +129 -374
  2. package/dist/mcp-server/config.d.ts +20 -0
  3. package/dist/mcp-server/config.d.ts.map +1 -0
  4. package/dist/mcp-server/config.js +125 -0
  5. package/dist/mcp-server/config.js.map +1 -0
  6. package/dist/mcp-server/index.d.ts +100 -0
  7. package/dist/mcp-server/index.d.ts.map +1 -0
  8. package/dist/mcp-server/index.js +1113 -0
  9. package/dist/mcp-server/index.js.map +1 -0
  10. package/dist/src/adaptive.d.ts +7 -0
  11. package/dist/src/adaptive.d.ts.map +1 -0
  12. package/dist/src/adaptive.js +49 -0
  13. package/dist/src/adaptive.js.map +1 -0
  14. package/dist/src/affect.d.ts +19 -0
  15. package/dist/src/affect.d.ts.map +1 -0
  16. package/dist/src/affect.js +72 -0
  17. package/dist/src/affect.js.map +1 -0
  18. package/dist/src/audrey.d.ts +140 -0
  19. package/dist/src/audrey.d.ts.map +1 -0
  20. package/dist/src/audrey.js +564 -0
  21. package/dist/src/audrey.js.map +1 -0
  22. package/dist/src/capsule.d.ts +68 -0
  23. package/dist/src/capsule.d.ts.map +1 -0
  24. package/dist/src/capsule.js +311 -0
  25. package/dist/src/capsule.js.map +1 -0
  26. package/dist/src/causal.d.ts +28 -0
  27. package/dist/src/causal.d.ts.map +1 -0
  28. package/dist/src/causal.js +65 -0
  29. package/dist/src/causal.js.map +1 -0
  30. package/dist/src/confidence.d.ts +12 -0
  31. package/dist/src/confidence.d.ts.map +1 -0
  32. package/dist/src/confidence.js +63 -0
  33. package/dist/src/confidence.js.map +1 -0
  34. package/dist/src/consolidate.d.ts +8 -0
  35. package/dist/src/consolidate.d.ts.map +1 -0
  36. package/dist/src/consolidate.js +218 -0
  37. package/dist/src/consolidate.js.map +1 -0
  38. package/dist/src/context.d.ts +3 -0
  39. package/dist/src/context.d.ts.map +1 -0
  40. package/dist/src/context.js +19 -0
  41. package/dist/src/context.js.map +1 -0
  42. package/dist/src/db.d.ts +12 -0
  43. package/dist/src/db.d.ts.map +1 -0
  44. package/dist/src/db.js +380 -0
  45. package/dist/src/db.js.map +1 -0
  46. package/dist/src/decay.d.ts +7 -0
  47. package/dist/src/decay.d.ts.map +1 -0
  48. package/dist/src/decay.js +68 -0
  49. package/dist/src/decay.js.map +1 -0
  50. package/dist/src/embedding.d.ts +57 -0
  51. package/dist/src/embedding.d.ts.map +1 -0
  52. package/dist/src/embedding.js +254 -0
  53. package/dist/src/embedding.js.map +1 -0
  54. package/dist/src/encode.d.ts +15 -0
  55. package/dist/src/encode.d.ts.map +1 -0
  56. package/dist/src/encode.js +36 -0
  57. package/dist/src/encode.js.map +1 -0
  58. package/dist/src/events.d.ts +69 -0
  59. package/dist/src/events.d.ts.map +1 -0
  60. package/dist/src/events.js +149 -0
  61. package/dist/src/events.js.map +1 -0
  62. package/dist/src/export.d.ts +3 -0
  63. package/dist/src/export.d.ts.map +1 -0
  64. package/dist/src/export.js +46 -0
  65. package/dist/src/export.js.map +1 -0
  66. package/dist/src/forget.d.ts +11 -0
  67. package/dist/src/forget.d.ts.map +1 -0
  68. package/dist/src/forget.js +105 -0
  69. package/dist/src/forget.js.map +1 -0
  70. package/dist/src/fts.d.ts +34 -0
  71. package/dist/src/fts.d.ts.map +1 -0
  72. package/dist/src/fts.js +117 -0
  73. package/dist/src/fts.js.map +1 -0
  74. package/dist/src/hybrid-recall.d.ts +37 -0
  75. package/dist/src/hybrid-recall.d.ts.map +1 -0
  76. package/dist/src/hybrid-recall.js +213 -0
  77. package/dist/src/hybrid-recall.js.map +1 -0
  78. package/dist/src/import.d.ts +4 -0
  79. package/dist/src/import.d.ts.map +1 -0
  80. package/dist/src/import.js +127 -0
  81. package/dist/src/import.js.map +1 -0
  82. package/dist/src/index.d.ts +22 -0
  83. package/dist/src/index.d.ts.map +1 -0
  84. package/{src → dist/src}/index.js +5 -13
  85. package/dist/src/index.js.map +1 -0
  86. package/dist/src/interference.d.ts +13 -0
  87. package/dist/src/interference.d.ts.map +1 -0
  88. package/dist/src/interference.js +45 -0
  89. package/dist/src/interference.js.map +1 -0
  90. package/dist/src/introspect.d.ts +4 -0
  91. package/dist/src/introspect.d.ts.map +1 -0
  92. package/dist/src/introspect.js +40 -0
  93. package/dist/src/introspect.js.map +1 -0
  94. package/dist/src/llm.d.ts +38 -0
  95. package/dist/src/llm.d.ts.map +1 -0
  96. package/dist/src/llm.js +167 -0
  97. package/dist/src/llm.js.map +1 -0
  98. package/dist/src/migrate.d.ts +6 -0
  99. package/dist/src/migrate.d.ts.map +1 -0
  100. package/dist/src/migrate.js +51 -0
  101. package/dist/src/migrate.js.map +1 -0
  102. package/dist/src/promote.d.ts +40 -0
  103. package/dist/src/promote.d.ts.map +1 -0
  104. package/dist/src/promote.js +200 -0
  105. package/dist/src/promote.js.map +1 -0
  106. package/dist/src/prompts.d.ts +16 -0
  107. package/dist/src/prompts.d.ts.map +1 -0
  108. package/{src → dist/src}/prompts.js +172 -203
  109. package/dist/src/prompts.js.map +1 -0
  110. package/dist/src/recall.d.ts +9 -0
  111. package/dist/src/recall.d.ts.map +1 -0
  112. package/dist/src/recall.js +432 -0
  113. package/dist/src/recall.js.map +1 -0
  114. package/dist/src/redact.d.ts +27 -0
  115. package/dist/src/redact.d.ts.map +1 -0
  116. package/dist/src/redact.js +228 -0
  117. package/dist/src/redact.js.map +1 -0
  118. package/dist/src/rollback.d.ts +8 -0
  119. package/dist/src/rollback.d.ts.map +1 -0
  120. package/dist/src/rollback.js +33 -0
  121. package/dist/src/rollback.js.map +1 -0
  122. package/dist/src/routes.d.ts +7 -0
  123. package/dist/src/routes.d.ts.map +1 -0
  124. package/dist/src/routes.js +226 -0
  125. package/dist/src/routes.js.map +1 -0
  126. package/dist/src/rules-compiler.d.ts +20 -0
  127. package/dist/src/rules-compiler.d.ts.map +1 -0
  128. package/dist/src/rules-compiler.js +143 -0
  129. package/dist/src/rules-compiler.js.map +1 -0
  130. package/dist/src/server.d.ts +12 -0
  131. package/dist/src/server.d.ts.map +1 -0
  132. package/dist/src/server.js +22 -0
  133. package/dist/src/server.js.map +1 -0
  134. package/dist/src/tool-trace.d.ts +37 -0
  135. package/dist/src/tool-trace.d.ts.map +1 -0
  136. package/dist/src/tool-trace.js +142 -0
  137. package/dist/src/tool-trace.js.map +1 -0
  138. package/dist/src/types.d.ts +446 -0
  139. package/dist/src/types.d.ts.map +1 -0
  140. package/dist/src/types.js +6 -0
  141. package/dist/src/types.js.map +1 -0
  142. package/dist/src/ulid.d.ts +3 -0
  143. package/dist/src/ulid.d.ts.map +1 -0
  144. package/dist/src/ulid.js +11 -0
  145. package/dist/src/ulid.js.map +1 -0
  146. package/dist/src/utils.d.ts +10 -0
  147. package/dist/src/utils.d.ts.map +1 -0
  148. package/dist/src/utils.js +41 -0
  149. package/dist/src/utils.js.map +1 -0
  150. package/dist/src/validate.d.ts +22 -0
  151. package/dist/src/validate.d.ts.map +1 -0
  152. package/dist/src/validate.js +109 -0
  153. package/dist/src/validate.js.map +1 -0
  154. package/docs/production-readiness.md +28 -0
  155. package/examples/fintech-ops-demo.js +1 -1
  156. package/examples/healthcare-ops-demo.js +1 -1
  157. package/examples/stripe-demo.js +1 -1
  158. package/package.json +34 -13
  159. package/benchmarks/baselines.js +0 -169
  160. package/benchmarks/cases.js +0 -421
  161. package/benchmarks/reference-results.js +0 -70
  162. package/benchmarks/report.js +0 -255
  163. package/benchmarks/run.js +0 -514
  164. package/mcp-server/config.js +0 -133
  165. package/mcp-server/index.js +0 -1265
  166. package/mcp-server/serve.js +0 -482
  167. package/src/adaptive.js +0 -53
  168. package/src/affect.js +0 -64
  169. package/src/audrey.js +0 -642
  170. package/src/causal.js +0 -95
  171. package/src/confidence.js +0 -120
  172. package/src/consolidate.js +0 -281
  173. package/src/context.js +0 -15
  174. package/src/db.js +0 -391
  175. package/src/decay.js +0 -84
  176. package/src/embedding.js +0 -260
  177. package/src/encode.js +0 -69
  178. package/src/export.js +0 -67
  179. package/src/forget.js +0 -111
  180. package/src/fts.js +0 -134
  181. package/src/import.js +0 -273
  182. package/src/interference.js +0 -51
  183. package/src/introspect.js +0 -48
  184. package/src/llm.js +0 -249
  185. package/src/migrate.js +0 -58
  186. package/src/recall.js +0 -573
  187. package/src/rollback.js +0 -42
  188. package/src/ulid.js +0 -18
  189. package/src/utils.js +0 -63
  190. package/src/validate.js +0 -172
  191. package/types/index.d.ts +0 -434
package/README.md CHANGED
@@ -4,472 +4,227 @@
4
4
  [![npm version](https://img.shields.io/npm/v/audrey.svg)](https://www.npmjs.com/package/audrey)
5
5
  [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
6
6
 
7
- Persistent memory for Claude Code and AI agents. Two commands, every session remembers.
7
+ Audrey is a persistent memory and continuity engine for Claude Code and AI agents.
8
8
 
9
- ```bash
10
- npx audrey install # 13 MCP memory tools
11
- npx audrey hooks install # automatic memory in every session
12
- ```
9
+ It gives an agent a local memory store, durable recall, consolidation, contradiction handling, a REST sidecar, MCP tools, and benchmark gates without adding external infrastructure.
13
10
 
14
- That's it. Claude Code now wakes up knowing what happened yesterday, recalls relevant context per-prompt, and consolidates learnings when the session ends. No cloud, no config files, no infrastructure — one SQLite file.
11
+ Requires Node.js 20+.
15
12
 
16
- Audrey also works as a standalone SDK, MCP server, and REST API for any AI agent framework.
13
+ ## Quick Start
17
14
 
18
- > **On `/dream`** — Anthropic recently shipped `/dream` for Claude Code memory maintenance. Audrey predates it and goes further: episodic-to-semantic consolidation, contradiction detection, confidence decay, emotional affect, causal reasoning, and source reliability weighting. `/dream` is a maintenance pass. Audrey is a cognitive memory architecture.
15
+ ### Claude Code
19
16
 
20
- ## Why Audrey
17
+ ```bash
18
+ npx audrey init
19
+ npx audrey doctor
20
+ ```
21
21
 
22
- Most AI memory tools are storage wrappers. They save facts, retrieve facts, and keep everything forever. That leaves real production problems unsolved:
22
+ This uses the default `local-offline` preset:
23
23
 
24
- - Old information stays weighted like new information.
25
- - Raw events never become reusable operating knowledge.
26
- - Conflicting facts quietly coexist.
27
- - Model-generated mistakes can get reinforced into false "truth."
24
+ - registers Audrey with Claude Code
25
+ - installs hooks for automatic recall and reflection
26
+ - uses local embeddings by default
27
+ - stores memory in one local SQLite-backed data directory
28
28
 
29
- Audrey models memory as a working system instead of a filing cabinet.
29
+ ### REST or Docker Sidecar
30
30
 
31
- | Brain Structure | Audrey Component | What It Does |
32
- |---|---|---|
33
- | Hippocampus | Episodic Memory | Fast capture of raw events and observations |
34
- | Neocortex | Semantic Memory | Consolidated principles and patterns |
35
- | Cerebellum | Procedural Memory | Learned workflows and conditional behaviors |
36
- | Sleep Replay | Dream Cycle | Consolidates episodes into principles and applies decay |
37
- | Prefrontal Cortex | Validation Engine | Truth-checking and contradiction detection |
38
- | Amygdala | Affect System | Emotional encoding, arousal-salience coupling, and mood-congruent recall |
39
-
40
- ## What You Get
41
-
42
- - Local SQLite-backed memory with `sqlite-vec`
43
- - MCP server for Claude Code with 13 memory tools
44
- - **Claude Code hooks integration** — automatic memory in every session (`npx audrey hooks install`)
45
- - JavaScript SDK for direct application use
46
- - **Git-friendly versioning** via JSON snapshots (`npx audrey snapshot` / `restore`)
47
- - **REST API server** - any language, any framework (`npx audrey serve`)
48
- - Health checks via `npx audrey status --json`
49
- - Benchmark harness with retrieval and lifecycle-operation tracks via `npm run bench:memory`
50
- - Regression gate for benchmark quality via `npm run bench:memory:check`
51
- - Optional local embeddings and optional hosted LLM providers
52
- - Strongest production fit today in financial services ops and healthcare ops
53
-
54
- ## Install
55
-
56
- ### MCP Server for Claude Code
31
+ ```bash
32
+ npx audrey init sidecar-prod
33
+ docker compose up -d --build
34
+ ```
35
+
36
+ Then verify:
57
37
 
58
38
  ```bash
59
- npx audrey install # Register 13 MCP memory tools
60
- npx audrey hooks install # Wire automatic memory into session lifecycle
39
+ npx audrey doctor
40
+ curl http://localhost:3487/health
61
41
  ```
62
42
 
63
- Audrey auto-detects providers from your environment:
43
+ ## Why Audrey
64
44
 
65
- - `GOOGLE_API_KEY` or `GEMINI_API_KEY` -> Gemini embeddings (3072d)
66
- - no embedding key -> local embeddings (384d, MiniLM, offline-capable)
67
- - `AUDREY_EMBEDDING_PROVIDER=openai` -> explicit OpenAI embeddings (1536d)
68
- - `ANTHROPIC_API_KEY` -> LLM-powered consolidation, contradiction detection, and reflection
45
+ - Local-first: memory lives in SQLite with `sqlite-vec`, not a hosted vector database.
46
+ - Practical: MCP, CLI, REST, JavaScript, Python, and Docker are all first-class.
47
+ - Durable: snapshot, restore, health checks, benchmark gates, and graceful shutdown are built in.
48
+ - Structured: Audrey does more than save notes. It consolidates, decays, tracks contradictions, and supports procedural memory.
69
49
 
70
- Quick checks:
50
+ ## What Ships
71
51
 
72
- ```bash
73
- npx audrey status
74
- npx audrey status --json
75
- npx audrey status --json --fail-on-unhealthy
76
- ```
52
+ - Claude Code MCP server with 13 memory tools
53
+ - Automatic hook-based recall and reflection for Claude Code sessions
54
+ - JavaScript SDK
55
+ - Python SDK packaged as `audrey-memory`
56
+ - REST API for sidecar deployment
57
+ - Docker and Compose deployment path
58
+ - Snapshot and restore for portable memory state
59
+ - Machine-readable health and benchmark gates
60
+ - Local benchmark harness with retrieval and lifecycle-operation tracks
61
+
62
+ ## Setup Presets
77
63
 
78
- ### SDK
64
+ `npx audrey init` supports four named presets:
65
+
66
+ | Preset | Best For | Behavior |
67
+ |---|---|---|
68
+ | `local-offline` | Claude Code on one machine | Local embeddings, MCP install, hooks install |
69
+ | `hosted-fast` | Claude Code with provider keys already present | Auto-picks hosted providers from env, MCP install, hooks install |
70
+ | `ci-mock` | CI and smoke tests | Mock embedding + LLM providers, no Claude-specific setup |
71
+ | `sidecar-prod` | REST API and Docker deployment | Sidecar-oriented defaults, no Claude-specific setup |
72
+
73
+ Useful checks:
79
74
 
80
75
  ```bash
81
- npm install audrey
76
+ npx audrey doctor
77
+ npx audrey status
78
+ npx audrey status --json --fail-on-unhealthy
82
79
  ```
83
80
 
84
- Zero external infrastructure. One SQLite file.
81
+ ## Use Audrey From Code
85
82
 
86
- ## Quick Start
83
+ ### JavaScript
87
84
 
88
85
  ```js
89
86
  import { Audrey } from 'audrey';
90
87
 
91
88
  const brain = new Audrey({
92
- dataDir: './agent-memory',
89
+ dataDir: './audrey-data',
93
90
  agent: 'support-agent',
94
91
  embedding: { provider: 'local', dimensions: 384 },
95
92
  });
96
93
 
97
94
  await brain.encode({
98
- content: 'Stripe API returned 429 above 100 req/s',
95
+ content: 'Stripe returns HTTP 429 above 100 req/s',
99
96
  source: 'direct-observation',
100
97
  tags: ['stripe', 'rate-limit'],
101
- context: { task: 'debugging', domain: 'payments' },
102
- affect: { valence: -0.4, arousal: 0.7, label: 'frustration' },
103
- });
104
-
105
- const memories = await brain.recall('stripe rate limits', {
106
- limit: 5,
107
- context: { task: 'debugging', domain: 'payments' },
108
98
  });
109
99
 
110
- const dream = await brain.dream();
111
- const briefing = await brain.greeting({ context: 'debugging stripe' });
100
+ const memories = await brain.recall('stripe rate limit');
112
101
 
113
102
  await brain.waitForIdle();
114
103
  brain.close();
115
104
  ```
116
105
 
117
- ## MCP Tools
118
-
119
- Every Claude Code session gets these tools after `npx audrey install`:
120
-
121
- - `memory_encode`
122
- - `memory_recall`
123
- - `memory_consolidate`
124
- - `memory_dream`
125
- - `memory_introspect`
126
- - `memory_resolve_truth`
127
- - `memory_export`
128
- - `memory_import`
129
- - `memory_forget`
130
- - `memory_decay`
131
- - `memory_status`
132
- - `memory_reflect`
133
- - `memory_greeting`
134
-
135
- ## CLI
136
-
137
- ```bash
138
- # Setup
139
- npx audrey install # Register MCP server with Claude Code
140
- npx audrey uninstall # Remove MCP server registration
141
- npx audrey hooks install # Wire Audrey into Claude Code hooks (automatic memory)
142
- npx audrey hooks uninstall # Remove Audrey hooks
143
-
144
- # Health and monitoring
145
- npx audrey status # Human-readable health report
146
- npx audrey status --json # Machine-readable health output
147
- npx audrey status --json --fail-on-unhealthy # CI gate
148
-
149
- # Session lifecycle (used by hooks automatically)
150
- npx audrey greeting # Load identity, principles, mood
151
- npx audrey greeting "auth" # With context-aware recall
152
- npx audrey recall "query" # Semantic memory search (returns hook-compatible JSON)
153
- npx audrey reflect # Consolidate learnings from stdin conversation + dream
154
-
155
- # Maintenance
156
- npx audrey dream # Full consolidation + decay cycle
157
- npx audrey reembed # Re-embed all memories after provider/dimension change
158
-
159
- # Versioning
160
- npx audrey snapshot # Export memories to timestamped JSON file
161
- npx audrey snapshot backup.json # Export to specific file
162
- npx audrey restore backup.json # Restore from snapshot (re-embeds with current provider)
163
- npx audrey restore backup.json --force # Overwrite existing memories
164
-
165
- # REST API server
166
- npx audrey serve # Start HTTP server on port 3487
167
- npx audrey serve 8080 # Custom port
168
- ```
169
-
170
- ## Hooks Integration
171
-
172
- Audrey integrates directly into Claude Code's hook lifecycle for automatic, zero-config memory in every session:
173
-
174
- ```bash
175
- npx audrey hooks install
176
- ```
177
-
178
- This configures four hooks in `~/.claude/settings.json`:
179
-
180
- | Hook Event | Command | What Happens |
181
- |---|---|---|
182
- | **SessionStart** | `npx audrey greeting` | Loads identity, learned principles, current mood, and recent memories |
183
- | **UserPromptSubmit** | `npx audrey recall` | Semantic search on every prompt — injects relevant memories as context |
184
- | **Stop** | `npx audrey reflect` | Extracts lasting learnings from the conversation, then runs a dream cycle |
185
- | **PostCompact** | `npx audrey greeting` | Re-injects critical memories after context window compaction |
186
-
187
- With hooks installed, Claude Code sessions automatically wake up with context, recall relevant memories per-prompt, and consolidate learnings when the session ends. No manual tool calls needed.
188
-
189
- ## REST API Server
190
-
191
- Turn Audrey into an HTTP service that any language or framework can use:
106
+ ### Python
192
107
 
193
108
  ```bash
194
- npx audrey serve # Start on port 3487
195
- npx audrey serve 8080 # Custom port
196
- AUDREY_API_KEY=secret npx audrey serve # With Bearer token auth
109
+ pip install audrey-memory
197
110
  ```
198
111
 
199
- Endpoints:
112
+ ```python
113
+ from audrey_memory import Audrey
200
114
 
201
- | Method | Path | Description |
202
- |--------|------|-------------|
203
- | `GET` | `/health` | Liveness probe |
204
- | `GET` | `/status` | Memory stats (introspect) |
205
- | `POST` | `/encode` | Store a memory (`{ content, source, tags?, context?, affect? }`) |
206
- | `POST` | `/recall` | Semantic search (`{ query, limit?, context? }`) |
207
- | `POST` | `/dream` | Full consolidation + decay cycle |
208
- | `POST` | `/consolidate` | Run consolidation only |
209
- | `POST` | `/forget` | Forget by `{ id }` or `{ query }` |
210
- | `POST` | `/snapshot` | Export all memories as JSON |
211
- | `POST` | `/restore` | Wipe and reimport from snapshot |
115
+ brain = Audrey(
116
+ base_url="http://127.0.0.1:3487",
117
+ api_key="secret",
118
+ agent="support-agent",
119
+ )
212
120
 
213
- Example from any language:
214
-
215
- ```bash
216
- # Store a memory
217
- curl -X POST http://localhost:3487/encode \
218
- -H "Content-Type: application/json" \
219
- -d '{"content": "The deploy failed due to OOM", "source": "direct-observation"}'
220
-
221
- # Search memories
222
- curl -X POST http://localhost:3487/recall \
223
- -H "Content-Type: application/json" \
224
- -d '{"query": "deploy failures", "limit": 5}'
121
+ memory_id = brain.encode(
122
+ "Stripe returns HTTP 429 above 100 req/s",
123
+ source="direct-observation",
124
+ )
125
+ results = brain.recall("stripe rate limit", limit=5)
126
+ brain.close()
225
127
  ```
226
128
 
227
- ## Versioning
228
-
229
- Audrey stores memories in SQLite with WAL mode, which isn't git-friendly. Instead, use JSON snapshots:
129
+ ## Key Commands
230
130
 
231
131
  ```bash
232
- # Save a checkpoint
233
- npx audrey snapshot
234
-
235
- # Commit it
236
- git add audrey-snapshot-*.json && git commit -m "memory checkpoint"
237
-
238
- # Restore on another machine or after a reset
239
- npx audrey restore audrey-snapshot-2026-03-24_15-30-00.json
240
- ```
241
-
242
- Snapshots are human-readable, diffable, and provider-agnostic. Embeddings are re-generated on import, so you can switch providers (e.g., local to Gemini) and restore seamlessly.
243
-
244
- ## Production Fit
245
-
246
- Audrey is strongest today in workflows where memory must stay local, reviewable, and durable:
247
-
248
- - **Financial services operations**: payments ops, fraud and dispute workflows, KYC/KYB review, internal policy assistants
249
- - **Healthcare operations**: care coordination, prior-auth workflows, intake and referral routing, internal staff knowledge assistants
250
-
251
- Audrey is a memory layer, not a compliance boundary. For regulated environments, pair it with application-level access control, encryption, retention, audit logging, and data-minimization rules.
252
-
253
- Production guide: [docs/production-readiness.md](docs/production-readiness.md)
254
-
255
- Industry demos:
256
-
257
- - [examples/fintech-ops-demo.js](examples/fintech-ops-demo.js)
258
- - [examples/healthcare-ops-demo.js](examples/healthcare-ops-demo.js)
259
-
260
- ## Core Concepts
261
-
262
- ### Memory Types
263
-
264
- - **Episodic**: raw events and observations
265
- - **Semantic**: consolidated principles
266
- - **Procedural**: reusable workflows and actions
267
- - **Causal**: relationships that explain why something happened
268
-
269
- ### Confidence
270
-
271
- Audrey scores memories using source reliability, evidence agreement, recency decay, and retrieval reinforcement. That helps keep direct observations above guesses and keeps stale or weakly supported knowledge from dominating recall.
272
-
273
- ### Dream Cycle
274
-
275
- `brain.dream()` runs the full maintenance path:
276
-
277
- 1. Consolidate related episodes into principles.
278
- 2. Apply decay so low-value memories lose weight over time.
279
- 3. Report memory health and current stats.
280
-
281
- ### Contradiction Handling
282
-
283
- When evidence conflicts, Audrey tracks the contradiction instead of silently picking a winner. Resolutions can stay open, be marked resolved, or become context-dependent.
284
-
285
- ## Configuration
286
-
287
- ```js
288
- const brain = new Audrey({
289
- dataDir: './audrey-data',
290
- agent: 'my-agent',
291
- embedding: {
292
- provider: 'local', // mock | local | gemini | openai
293
- dimensions: 384,
294
- device: 'gpu',
295
- },
296
- llm: {
297
- provider: 'anthropic', // mock | anthropic | openai
298
- apiKey: process.env.ANTHROPIC_API_KEY,
299
- },
300
- consolidation: {
301
- minEpisodes: 3,
302
- },
303
- context: {
304
- enabled: true,
305
- weight: 0.3,
306
- },
307
- affect: {
308
- enabled: true,
309
- weight: 0.2,
310
- },
311
- decay: {
312
- dormantThreshold: 0.1,
313
- },
314
- });
315
- ```
316
-
317
- ## Operations
132
+ # Setup
133
+ npx audrey init
134
+ npx audrey init hosted-fast
135
+ npx audrey init ci-mock
136
+ npx audrey init sidecar-prod
318
137
 
319
- Recommended production workflow:
138
+ # Claude Code integration
139
+ npx audrey install
140
+ npx audrey hooks install
141
+ npx audrey hooks uninstall
142
+ npx audrey uninstall
320
143
 
321
- ```bash
322
- # Health checks
144
+ # Health and maintenance
145
+ npx audrey doctor
323
146
  npx audrey status
324
- npx audrey status --json --fail-on-unhealthy
325
-
326
- # Scheduled maintenance
327
147
  npx audrey dream
328
-
329
- # Repair vector/index drift after provider or dimension changes
330
148
  npx audrey reembed
331
149
 
332
- # Version control your memories
150
+ # Versioning
333
151
  npx audrey snapshot
334
- npx audrey restore <file> --force
335
-
336
- # Run the benchmark harness
337
- npm run bench:memory
152
+ npx audrey restore backup.json --force
338
153
 
339
- # Fail CI if Audrey drops below benchmark guardrails
340
- npm run bench:memory:check
154
+ # Sidecar
155
+ npx audrey serve
156
+ docker compose up -d --build
341
157
  ```
342
158
 
343
- ## Benchmarking
344
-
345
- Audrey now ships with a memory benchmark harness built for three purposes:
159
+ ## Benchmarks
346
160
 
347
- - measure Audrey against naive local baselines on LongMemEval-style memory abilities plus privacy and abstention checks
348
- - measure Audrey on lifecycle operations that other memory systems usually hand-wave: update, overwrite, delete, merge, and abstain
349
- - keep Audrey grounded against published LoCoMo results from leading memory systems
350
-
351
- Run it with:
161
+ Audrey ships with a benchmark harness and release gate:
352
162
 
353
163
  ```bash
354
164
  npm run bench:memory
165
+ npm run bench:memory:check
355
166
  ```
356
167
 
357
- Artifacts land in `benchmarks/output/` as JSON, SVG charts, and an HTML report.
168
+ The benchmark suite measures:
358
169
 
359
- For CI and release gates:
170
+ - retrieval behavior
171
+ - update and overwrite behavior
172
+ - delete and abstain behavior
173
+ - semantic and procedural merge behavior
360
174
 
361
- ```bash
362
- npm run bench:memory:check
363
- ```
175
+ Current repo snapshot:
364
176
 
365
- That command fails if Audrey drops below its minimum local score, local pass rate, or required margin over the strongest naive baseline.
177
+ ![Audrey local benchmark](docs/assets/benchmarks/local-benchmark.svg)
366
178
 
367
- For track-specific runs:
179
+ For detailed methodology, published comparison anchors, and generated reports, see [docs/benchmarking.md](docs/benchmarking.md).
368
180
 
369
- ```bash
370
- npm run bench:memory:retrieval
371
- npm run bench:memory:operations
372
- ```
181
+ ## Production
373
182
 
374
- For committed GitHub-friendly charts:
183
+ Audrey is strongest in workflows where memory must stay local, reviewable, and durable. It already fits well as a sidecar for internal agents in operational domains like financial services and healthcare operations, but it is a memory layer, not a compliance boundary.
375
184
 
376
- ```bash
377
- npm run bench:memory:readme-assets
378
- ```
185
+ Production guide: [docs/production-readiness.md](docs/production-readiness.md)
379
186
 
380
- ### README Snapshot
187
+ Examples:
381
188
 
382
- Local Audrey-vs-baseline results:
189
+ - [examples/fintech-ops-demo.js](examples/fintech-ops-demo.js)
190
+ - [examples/healthcare-ops-demo.js](examples/healthcare-ops-demo.js)
191
+ - [examples/stripe-demo.js](examples/stripe-demo.js)
383
192
 
384
- ![Audrey local memory benchmark](docs/assets/benchmarks/local-benchmark.svg)
193
+ ## Environment
385
194
 
386
- Lifecycle operations benchmark:
195
+ Starter config:
387
196
 
388
- ![Audrey memory operations benchmark](docs/assets/benchmarks/operations-benchmark.svg)
197
+ - [.env.example](.env.example)
198
+ - [.env.docker.example](.env.docker.example)
389
199
 
390
- Published comparison anchors from current LLM memory systems:
200
+ Key environment variables:
391
201
 
392
- ![Published LLM memory benchmark comparison](docs/assets/benchmarks/published-memory-standards.svg)
202
+ - `AUDREY_DATA_DIR`
203
+ - `AUDREY_EMBEDDING_PROVIDER`
204
+ - `AUDREY_LLM_PROVIDER`
205
+ - `AUDREY_DEVICE`
206
+ - `AUDREY_API_KEY`
207
+ - `AUDREY_HOST`
208
+ - `AUDREY_PORT`
393
209
 
394
- **Current deterministic CI snapshot** (`node benchmarks/run.js --provider mock --dimensions 64`):
210
+ ## Documentation
395
211
 
396
- | Local track | Audrey | Best Baseline |
397
- |---|---|---|
398
- | Combined local benchmark | **100.0%** | 41.7% |
399
- | Retrieval capabilities | **100.0%** | 56.3% |
400
- | Memory operations | **100.0%** | 25.0% |
401
-
402
- Retrieval-family breakdown:
403
-
404
- | Category | Audrey | Vector Only | Best Baseline |
405
- |---|---|---|---|
406
- | Information Extraction | 100% | 100% | 100% |
407
- | Knowledge Updates | 100% | 50% | 50% |
408
- | Multi-Session Reasoning | 100% | 100% | 100% |
409
- | Temporal Reasoning | 100% | 100% | 100% |
410
- | Abstention | 100% | 50% | 50% |
411
- | Conflict Resolution | 100% | 50% | 50% |
412
- | Procedural Learning | 100% | 0% | 0% |
413
- | Privacy | 100% | 0% | 0% |
414
-
415
- Operation-family breakdown:
416
-
417
- | Operation | Audrey | Vector Only | Best Baseline |
418
- |---|---|---|---|
419
- | Update / Overwrite | 100% | 50% | 50% |
420
- | Delete + Abstain | 100% | 0% | 50% |
421
- | Semantic Merge | 100% | 0% | 0% |
422
- | Procedural Merge | 100% | 0% | 0% |
423
-
424
- Published comparison anchors from the field (different benchmarks and conditions - included for field context, not direct comparison):
425
-
426
- | System | Benchmark | Score | What it represents |
427
- |---|---|---|---|
428
- | **Audrey** | Internal retrieval + operations benchmark | **100.0%** | Update, overwrite, delete, merge, abstention, consolidation, privacy |
429
- | MIRIX | Published LoCoMo | 85.4% | Typed multimodal memory |
430
- | Letta Filesystem | Published LoCoMo | 74.0% | Context-engineering |
431
- | Mem0 Graph Memory | Published LoCoMo | 68.5% | Graph memory |
432
- | Mem0 | Published LoCoMo | 66.9% | Production baseline |
433
-
434
- Primary comparison sources:
435
-
436
- - [MIRIX paper](https://arxiv.org/abs/2507.07957)
437
- - [Mem0 paper](https://arxiv.org/abs/2504.19413)
438
- - [Letta benchmark write-up](https://www.letta.com/blog/benchmarking-ai-agent-memory)
439
- - [LongMemEval paper](https://arxiv.org/abs/2410.10813)
440
-
441
- Benchmark guide: [docs/benchmarking.md](docs/benchmarking.md)
442
-
443
- ## Repository
444
-
445
- - Contributing guide: [CONTRIBUTING.md](CONTRIBUTING.md)
446
- - Security policy: [SECURITY.md](SECURITY.md)
447
- - CI workflow: [.github/workflows/ci.yml](.github/workflows/ci.yml)
448
- - Benchmarking guide: [docs/benchmarking.md](docs/benchmarking.md)
212
+ - [docs/benchmarking.md](docs/benchmarking.md)
213
+ - [docs/production-readiness.md](docs/production-readiness.md)
214
+ - [CONTRIBUTING.md](CONTRIBUTING.md)
215
+ - [SECURITY.md](SECURITY.md)
449
216
 
450
217
  ## Development
451
218
 
452
219
  ```bash
453
220
  npm ci
454
221
  npm test
455
- npm run pack:check
456
- npm run bench:memory
457
- npm run bench:memory:retrieval
458
- npm run bench:memory:operations
459
222
  npm run bench:memory:check
460
- npm run bench:memory:readme-assets
223
+ npm run pack:check
224
+ python -m unittest discover -s python/tests -v
225
+ python -m build --no-isolation python
461
226
  ```
462
227
 
463
- Current validated baseline:
464
-
465
- - `npm test`
466
- - `npm run pack:check`
467
- - `npm run bench:memory`
468
- - `npm run bench:memory:retrieval`
469
- - `npm run bench:memory:operations`
470
- - `npm run bench:memory:check`
471
- - `npm run bench:memory:readme-assets`
472
-
473
228
  ## License
474
229
 
475
230
  MIT. See [LICENSE](LICENSE).
@@ -0,0 +1,20 @@
1
+ import type { AudreyConfig, EmbeddingConfig, LLMConfig } from '../src/types.js';
2
+ export declare const VERSION = "0.20.0";
3
+ export declare const SERVER_NAME = "audrey-memory";
4
+ export declare const DEFAULT_DATA_DIR: string;
5
+ export declare const MCP_ENTRYPOINT: string;
6
+ export declare function resolveDataDir(env?: Record<string, string | undefined>): string;
7
+ /**
8
+ * Resolves which embedding provider to use.
9
+ * Priority: explicit config -> gemini (if GOOGLE_API_KEY exists) -> local
10
+ * OpenAI is NEVER auto-selected -- must be set explicitly via AUDREY_EMBEDDING_PROVIDER=openai.
11
+ */
12
+ export declare function resolveEmbeddingProvider(env: Record<string, string | undefined>, explicit?: string | undefined): EmbeddingConfig & {
13
+ dimensions: number;
14
+ };
15
+ export declare function resolveLLMProvider(env: Record<string, string | undefined>, explicit?: string | undefined): (LLMConfig & {
16
+ apiKey?: string;
17
+ }) | null;
18
+ export declare function buildAudreyConfig(): AudreyConfig;
19
+ export declare function buildInstallArgs(env?: Record<string, string | undefined>): string[];
20
+ //# sourceMappingURL=config.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../mcp-server/config.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEhF,eAAO,MAAM,OAAO,WAAW,CAAC;AAChC,eAAO,MAAM,WAAW,kBAAkB,CAAC;AAC3C,eAAO,MAAM,gBAAgB,QAAqC,CAAC;AACnE,eAAO,MAAM,cAAc,QAAwD,CAAC;AAyBpF,wBAAgB,cAAc,CAAC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GAAG,MAAM,CAE5F;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EACvC,QAAQ,GAAE,MAAM,GAAG,SAA4C,GAC9D,eAAe,GAAG;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,CAkB1C;AAED,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EACvC,QAAQ,GAAE,MAAM,GAAG,SAAsC,GACxD,CAAC,SAAS,GAAG;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,IAAI,CAoB1C;AAED,wBAAgB,iBAAiB,IAAI,YAAY,CAehD;AAED,wBAAgB,gBAAgB,CAAC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GAAG,MAAM,EAAE,CAoChG"}