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.
- package/README.md +129 -374
- package/dist/mcp-server/config.d.ts +20 -0
- package/dist/mcp-server/config.d.ts.map +1 -0
- package/dist/mcp-server/config.js +125 -0
- package/dist/mcp-server/config.js.map +1 -0
- package/dist/mcp-server/index.d.ts +100 -0
- package/dist/mcp-server/index.d.ts.map +1 -0
- package/dist/mcp-server/index.js +1113 -0
- package/dist/mcp-server/index.js.map +1 -0
- package/dist/src/adaptive.d.ts +7 -0
- package/dist/src/adaptive.d.ts.map +1 -0
- package/dist/src/adaptive.js +49 -0
- package/dist/src/adaptive.js.map +1 -0
- package/dist/src/affect.d.ts +19 -0
- package/dist/src/affect.d.ts.map +1 -0
- package/dist/src/affect.js +72 -0
- package/dist/src/affect.js.map +1 -0
- package/dist/src/audrey.d.ts +140 -0
- package/dist/src/audrey.d.ts.map +1 -0
- package/dist/src/audrey.js +564 -0
- package/dist/src/audrey.js.map +1 -0
- package/dist/src/capsule.d.ts +68 -0
- package/dist/src/capsule.d.ts.map +1 -0
- package/dist/src/capsule.js +311 -0
- package/dist/src/capsule.js.map +1 -0
- package/dist/src/causal.d.ts +28 -0
- package/dist/src/causal.d.ts.map +1 -0
- package/dist/src/causal.js +65 -0
- package/dist/src/causal.js.map +1 -0
- package/dist/src/confidence.d.ts +12 -0
- package/dist/src/confidence.d.ts.map +1 -0
- package/dist/src/confidence.js +63 -0
- package/dist/src/confidence.js.map +1 -0
- package/dist/src/consolidate.d.ts +8 -0
- package/dist/src/consolidate.d.ts.map +1 -0
- package/dist/src/consolidate.js +218 -0
- package/dist/src/consolidate.js.map +1 -0
- package/dist/src/context.d.ts +3 -0
- package/dist/src/context.d.ts.map +1 -0
- package/dist/src/context.js +19 -0
- package/dist/src/context.js.map +1 -0
- package/dist/src/db.d.ts +12 -0
- package/dist/src/db.d.ts.map +1 -0
- package/dist/src/db.js +380 -0
- package/dist/src/db.js.map +1 -0
- package/dist/src/decay.d.ts +7 -0
- package/dist/src/decay.d.ts.map +1 -0
- package/dist/src/decay.js +68 -0
- package/dist/src/decay.js.map +1 -0
- package/dist/src/embedding.d.ts +57 -0
- package/dist/src/embedding.d.ts.map +1 -0
- package/dist/src/embedding.js +254 -0
- package/dist/src/embedding.js.map +1 -0
- package/dist/src/encode.d.ts +15 -0
- package/dist/src/encode.d.ts.map +1 -0
- package/dist/src/encode.js +36 -0
- package/dist/src/encode.js.map +1 -0
- package/dist/src/events.d.ts +69 -0
- package/dist/src/events.d.ts.map +1 -0
- package/dist/src/events.js +149 -0
- package/dist/src/events.js.map +1 -0
- package/dist/src/export.d.ts +3 -0
- package/dist/src/export.d.ts.map +1 -0
- package/dist/src/export.js +46 -0
- package/dist/src/export.js.map +1 -0
- package/dist/src/forget.d.ts +11 -0
- package/dist/src/forget.d.ts.map +1 -0
- package/dist/src/forget.js +105 -0
- package/dist/src/forget.js.map +1 -0
- package/dist/src/fts.d.ts +34 -0
- package/dist/src/fts.d.ts.map +1 -0
- package/dist/src/fts.js +117 -0
- package/dist/src/fts.js.map +1 -0
- package/dist/src/hybrid-recall.d.ts +37 -0
- package/dist/src/hybrid-recall.d.ts.map +1 -0
- package/dist/src/hybrid-recall.js +213 -0
- package/dist/src/hybrid-recall.js.map +1 -0
- package/dist/src/import.d.ts +4 -0
- package/dist/src/import.d.ts.map +1 -0
- package/dist/src/import.js +127 -0
- package/dist/src/import.js.map +1 -0
- package/dist/src/index.d.ts +22 -0
- package/dist/src/index.d.ts.map +1 -0
- package/{src → dist/src}/index.js +5 -13
- package/dist/src/index.js.map +1 -0
- package/dist/src/interference.d.ts +13 -0
- package/dist/src/interference.d.ts.map +1 -0
- package/dist/src/interference.js +45 -0
- package/dist/src/interference.js.map +1 -0
- package/dist/src/introspect.d.ts +4 -0
- package/dist/src/introspect.d.ts.map +1 -0
- package/dist/src/introspect.js +40 -0
- package/dist/src/introspect.js.map +1 -0
- package/dist/src/llm.d.ts +38 -0
- package/dist/src/llm.d.ts.map +1 -0
- package/dist/src/llm.js +167 -0
- package/dist/src/llm.js.map +1 -0
- package/dist/src/migrate.d.ts +6 -0
- package/dist/src/migrate.d.ts.map +1 -0
- package/dist/src/migrate.js +51 -0
- package/dist/src/migrate.js.map +1 -0
- package/dist/src/promote.d.ts +40 -0
- package/dist/src/promote.d.ts.map +1 -0
- package/dist/src/promote.js +200 -0
- package/dist/src/promote.js.map +1 -0
- package/dist/src/prompts.d.ts +16 -0
- package/dist/src/prompts.d.ts.map +1 -0
- package/{src → dist/src}/prompts.js +172 -203
- package/dist/src/prompts.js.map +1 -0
- package/dist/src/recall.d.ts +9 -0
- package/dist/src/recall.d.ts.map +1 -0
- package/dist/src/recall.js +432 -0
- package/dist/src/recall.js.map +1 -0
- package/dist/src/redact.d.ts +27 -0
- package/dist/src/redact.d.ts.map +1 -0
- package/dist/src/redact.js +228 -0
- package/dist/src/redact.js.map +1 -0
- package/dist/src/rollback.d.ts +8 -0
- package/dist/src/rollback.d.ts.map +1 -0
- package/dist/src/rollback.js +33 -0
- package/dist/src/rollback.js.map +1 -0
- package/dist/src/routes.d.ts +7 -0
- package/dist/src/routes.d.ts.map +1 -0
- package/dist/src/routes.js +226 -0
- package/dist/src/routes.js.map +1 -0
- package/dist/src/rules-compiler.d.ts +20 -0
- package/dist/src/rules-compiler.d.ts.map +1 -0
- package/dist/src/rules-compiler.js +143 -0
- package/dist/src/rules-compiler.js.map +1 -0
- package/dist/src/server.d.ts +12 -0
- package/dist/src/server.d.ts.map +1 -0
- package/dist/src/server.js +22 -0
- package/dist/src/server.js.map +1 -0
- package/dist/src/tool-trace.d.ts +37 -0
- package/dist/src/tool-trace.d.ts.map +1 -0
- package/dist/src/tool-trace.js +142 -0
- package/dist/src/tool-trace.js.map +1 -0
- package/dist/src/types.d.ts +446 -0
- package/dist/src/types.d.ts.map +1 -0
- package/dist/src/types.js +6 -0
- package/dist/src/types.js.map +1 -0
- package/dist/src/ulid.d.ts +3 -0
- package/dist/src/ulid.d.ts.map +1 -0
- package/dist/src/ulid.js +11 -0
- package/dist/src/ulid.js.map +1 -0
- package/dist/src/utils.d.ts +10 -0
- package/dist/src/utils.d.ts.map +1 -0
- package/dist/src/utils.js +41 -0
- package/dist/src/utils.js.map +1 -0
- package/dist/src/validate.d.ts +22 -0
- package/dist/src/validate.d.ts.map +1 -0
- package/dist/src/validate.js +109 -0
- package/dist/src/validate.js.map +1 -0
- package/docs/production-readiness.md +28 -0
- package/examples/fintech-ops-demo.js +1 -1
- package/examples/healthcare-ops-demo.js +1 -1
- package/examples/stripe-demo.js +1 -1
- package/package.json +34 -13
- package/benchmarks/baselines.js +0 -169
- package/benchmarks/cases.js +0 -421
- package/benchmarks/reference-results.js +0 -70
- package/benchmarks/report.js +0 -255
- package/benchmarks/run.js +0 -514
- package/mcp-server/config.js +0 -133
- package/mcp-server/index.js +0 -1265
- package/mcp-server/serve.js +0 -482
- package/src/adaptive.js +0 -53
- package/src/affect.js +0 -64
- package/src/audrey.js +0 -642
- package/src/causal.js +0 -95
- package/src/confidence.js +0 -120
- package/src/consolidate.js +0 -281
- package/src/context.js +0 -15
- package/src/db.js +0 -391
- package/src/decay.js +0 -84
- package/src/embedding.js +0 -260
- package/src/encode.js +0 -69
- package/src/export.js +0 -67
- package/src/forget.js +0 -111
- package/src/fts.js +0 -134
- package/src/import.js +0 -273
- package/src/interference.js +0 -51
- package/src/introspect.js +0 -48
- package/src/llm.js +0 -249
- package/src/migrate.js +0 -58
- package/src/recall.js +0 -573
- package/src/rollback.js +0 -42
- package/src/ulid.js +0 -18
- package/src/utils.js +0 -63
- package/src/validate.js +0 -172
- package/types/index.d.ts +0 -434
package/README.md
CHANGED
|
@@ -4,472 +4,227 @@
|
|
|
4
4
|
[](https://www.npmjs.com/package/audrey)
|
|
5
5
|
[](LICENSE)
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
Audrey is a persistent memory and continuity engine for Claude Code and AI agents.
|
|
8
8
|
|
|
9
|
-
|
|
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
|
-
|
|
11
|
+
Requires Node.js 20+.
|
|
15
12
|
|
|
16
|
-
|
|
13
|
+
## Quick Start
|
|
17
14
|
|
|
18
|
-
|
|
15
|
+
### Claude Code
|
|
19
16
|
|
|
20
|
-
|
|
17
|
+
```bash
|
|
18
|
+
npx audrey init
|
|
19
|
+
npx audrey doctor
|
|
20
|
+
```
|
|
21
21
|
|
|
22
|
-
|
|
22
|
+
This uses the default `local-offline` preset:
|
|
23
23
|
|
|
24
|
-
-
|
|
25
|
-
-
|
|
26
|
-
-
|
|
27
|
-
-
|
|
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
|
-
|
|
29
|
+
### REST or Docker Sidecar
|
|
30
30
|
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
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
|
|
60
|
-
|
|
39
|
+
npx audrey doctor
|
|
40
|
+
curl http://localhost:3487/health
|
|
61
41
|
```
|
|
62
42
|
|
|
63
|
-
|
|
43
|
+
## Why Audrey
|
|
64
44
|
|
|
65
|
-
-
|
|
66
|
-
-
|
|
67
|
-
-
|
|
68
|
-
-
|
|
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
|
-
|
|
50
|
+
## What Ships
|
|
71
51
|
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
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
|
-
|
|
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
|
-
|
|
76
|
+
npx audrey doctor
|
|
77
|
+
npx audrey status
|
|
78
|
+
npx audrey status --json --fail-on-unhealthy
|
|
82
79
|
```
|
|
83
80
|
|
|
84
|
-
|
|
81
|
+
## Use Audrey From Code
|
|
85
82
|
|
|
86
|
-
|
|
83
|
+
### JavaScript
|
|
87
84
|
|
|
88
85
|
```js
|
|
89
86
|
import { Audrey } from 'audrey';
|
|
90
87
|
|
|
91
88
|
const brain = new Audrey({
|
|
92
|
-
dataDir: './
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
112
|
+
```python
|
|
113
|
+
from audrey_memory import Audrey
|
|
200
114
|
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
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
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
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
|
-
##
|
|
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
|
-
#
|
|
233
|
-
npx audrey
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
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
|
-
|
|
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
|
-
|
|
322
|
-
|
|
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
|
-
#
|
|
150
|
+
# Versioning
|
|
333
151
|
npx audrey snapshot
|
|
334
|
-
npx audrey restore
|
|
335
|
-
|
|
336
|
-
# Run the benchmark harness
|
|
337
|
-
npm run bench:memory
|
|
152
|
+
npx audrey restore backup.json --force
|
|
338
153
|
|
|
339
|
-
#
|
|
340
|
-
|
|
154
|
+
# Sidecar
|
|
155
|
+
npx audrey serve
|
|
156
|
+
docker compose up -d --build
|
|
341
157
|
```
|
|
342
158
|
|
|
343
|
-
##
|
|
344
|
-
|
|
345
|
-
Audrey now ships with a memory benchmark harness built for three purposes:
|
|
159
|
+
## Benchmarks
|
|
346
160
|
|
|
347
|
-
|
|
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
|
-
|
|
168
|
+
The benchmark suite measures:
|
|
358
169
|
|
|
359
|
-
|
|
170
|
+
- retrieval behavior
|
|
171
|
+
- update and overwrite behavior
|
|
172
|
+
- delete and abstain behavior
|
|
173
|
+
- semantic and procedural merge behavior
|
|
360
174
|
|
|
361
|
-
|
|
362
|
-
npm run bench:memory:check
|
|
363
|
-
```
|
|
175
|
+
Current repo snapshot:
|
|
364
176
|
|
|
365
|
-
|
|
177
|
+

|
|
366
178
|
|
|
367
|
-
For
|
|
179
|
+
For detailed methodology, published comparison anchors, and generated reports, see [docs/benchmarking.md](docs/benchmarking.md).
|
|
368
180
|
|
|
369
|
-
|
|
370
|
-
npm run bench:memory:retrieval
|
|
371
|
-
npm run bench:memory:operations
|
|
372
|
-
```
|
|
181
|
+
## Production
|
|
373
182
|
|
|
374
|
-
|
|
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
|
-
|
|
377
|
-
npm run bench:memory:readme-assets
|
|
378
|
-
```
|
|
185
|
+
Production guide: [docs/production-readiness.md](docs/production-readiness.md)
|
|
379
186
|
|
|
380
|
-
|
|
187
|
+
Examples:
|
|
381
188
|
|
|
382
|
-
|
|
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
|
-
|
|
193
|
+
## Environment
|
|
385
194
|
|
|
386
|
-
|
|
195
|
+
Starter config:
|
|
387
196
|
|
|
388
|
-
|
|
197
|
+
- [.env.example](.env.example)
|
|
198
|
+
- [.env.docker.example](.env.docker.example)
|
|
389
199
|
|
|
390
|
-
|
|
200
|
+
Key environment variables:
|
|
391
201
|
|
|
392
|
-
|
|
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
|
-
|
|
210
|
+
## Documentation
|
|
395
211
|
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
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
|
|
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"}
|