Ambient Memory

为 AI 智能体提供零配置的本地环境记忆:加密的 SQLite 保管库和 MCP 工具(search、recent、context、relations),适用于 Cursor 和 Claude Desktop。它会被动记住文件、屏幕会话和浏览器历史记录。TypeScript,MIT,v0.3.0。此版本不包含遥测或同步功能。目前尚未发布到 npm;请从 GitHub 仓库安装。

文档

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