ambient-memory
Zero-config ambient memory for AI engineers — a local-first context layer that passively remembers what you worked on and exposes it to Cursor / Claude Desktop over MCP.
No Markdown vault. No Git sync. No OAuth. No native C++ / node-gyp install. After npm publish:```bash
npx -y ambient-memory init
npx -y ambient-memory start --screen auto
npx -y ambient-memory mcp
``````mermaid
flowchart LR
subgraph Capture
W[File watcher]
S[Screen sessions]
B[Browser history]
end
subgraph Daemon["Daemon (sole SQLite owner)"]
DB[(node:sqlite / sql.js WASM)]
IPC[Unix socket / named pipe]
end
subgraph Clients
CLI[ambient CLI]
MCP[MCP stdio]
end
W --> DB
S --> DB
B --> DB
DB --- IPC
IPC --> CLI
IPC --> MCP
## Why v0.3
1. **True zero-config install** — `node:sqlite` on Node 22+, `sql.js` WASM fallback on Node 20. No `better-sqlite3`.
2. **Daemon-owned vault** — only the daemon opens/seals SQLite; CLI/MCP are IPC clients (no seal races).
3. **npx-ready** — `ambient` and `ambient-memory` bins for `npx -y ambient-memory mcp`.
4. **Honest crypto** — AES-GCM field encryption + sealed `.enc` at rest; FTS is redacted plaintext while unlocked (documented, not theater).
5. **Noise control** — ignore Slack/Spotify/etc., dedupe focus churn, session summarization for signal-heavy `memory_context`.
## Install
Requires **Node.js 20+** (22+ preferred for built-in SQLite).```bash
# after publish
npx -y ambient-memory init
npx -y ambient-memory start --screen auto # headless: --screen simulated
# from this repo (pre-publish)
npm install
npm test
node ./bin/ambient.js init
MCP — Cursor```json
{
"mcpServers": {
"ambient-memory": {
"command": "npx",
"args": ["-y", "ambient-memory", "mcp"]
}
}
}
### MCP — Claude Desktop```json
{
"mcpServers": {
"ambient-memory": {
"command": "npx",
"args": ["-y", "ambient-memory", "mcp"]
}
}
}
mcp auto-starts the daemon if needed. Tools:
memory_search · memory_recent · memory_get · memory_context · memory_relate · memory_status
CLI```bash
ambient-memory init | start | stop | status | doctor
ambient-memory search "query" [--type file,url] [--since-mins 60]
ambient-memory recent | context --minutes 30 [--json]
ambient-memory forget "query" --yes | forget --all --yes
ambient-memory mcp
## Privacy & crypto (honest)
| Layer | Behavior |
|-------|----------|
| Entity fields | AES-256-GCM |
| At rest | `memory.db.enc` only when daemon stopped |
| FTS while unlocked | Redacted **plaintext** (search tradeoff) |
| Network | No telemetry / sync in v0.3 |
| Process model | Daemon owns DB; clients use IPC |
See SECURITY.md.
## Architecture
- **Daemon** watches Documents/Desktop/Downloads/cwd; indexes screen/browser with noise filters
- **Store** SQLite via `node:sqlite` or `sql.js`; FTS5/BM25; field encryption; seal-on-stop
- **IPC** Unix socket `~/.ambient-memory/ambient.sock` (Windows named pipe)
- **CLI / MCP** never open SQLite directly in normal operation
Force WASM backend: `AMBIENT_SQLITE_BACKEND=sql.js`. Force file key: `--file-key` / `AMBIENT_FORCE_FILE_KEY=1`.
## Development```bash
npm install && npm test && npm run demo
Version
0.3.0 — breaking: no native SQLite addon; daemon-owned IPC; noise control; npx bins.
License
MIT
