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.

Documentação

ambient-memory

CI npm License: MIT Node MCP

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

  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).

# 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)

LayerBehavior
Entity fieldsAES-256-GCM
At restmemory.db.enc only when daemon stopped
FTS while unlockedRedacted plaintext (search tradeoff)
NetworkNo telemetry / sync in v0.3
Process modelDaemon 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

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