Ambient Memory
Zero-config local ambient memory for AI agents: an encrypted SQLite vault and MCP tools (search, recent, context, relations) for Cursor and Claude Desktop. It passively remembers files, screen sessions and browser history. TypeScript, MIT, v0.3.0. No telemetry or sync in this release. Not on npm yet; install from the GitHub repository.
Dokumentasi
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:
npx -y ambient-memory init
npx -y ambient-memory start --screen auto
npx -y ambient-memory mcp
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
- True zero-config install —
node:sqliteon Node 22+,sql.jsWASM fallback on Node 20. Nobetter-sqlite3. - Daemon-owned vault — only the daemon opens/seals SQLite; CLI/MCP are IPC clients (no seal races).
- npx-ready —
ambientandambient-memorybins fornpx -y ambient-memory mcp. - Honest crypto — AES-GCM field encryption + sealed
.encat rest; FTS is redacted plaintext while unlocked (documented, not theater). - 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).
# 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
{
"mcpServers": {
"ambient-memory": {
"command": "npx",
"args": ["-y", "ambient-memory", "mcp"]
}
}
}
MCP — Claude Desktop
{
"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
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:sqliteorsql.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
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