Labs · Ambient Memory · summary on jarvisosorio.com

Ambient Memory documentation

Ambient Memory (ambient-memory) is a local-first context layer for AI engineers. It passively remembers what you worked on and exposes that memory to Cursor and Claude Desktop over the Model Context Protocol (MCP).

It does not use a Markdown vault, Git sync, OAuth, or a native C++ / node-gyp install. Current version: 0.3.0. License: MIT. Source: github.com/JarvisOsorio/ambient-memory.

View the GitHub repository Short project page

What it is for

AI engineers who want a local, encrypted memory vault for coding agents running in Cursor or Claude Desktop, without a hosted memory service.

Why v0.3

1. Zero-config install — storage uses Node’s built-in node:sqlite on Node 22+, with a sql.js WASM fallback on Node 20. There is no better-sqlite3 native addon.
2. Daemon-owned vault — only the daemon opens and seals SQLite. The CLI and MCP server are IPC clients, which avoids seal races from concurrent database opens.
3. npx-ready bins — the package defines ambient and ambient-memory for npx -y ambient-memory mcp once the package is on npm.
4. Documented crypto tradeoff — entity fields are encrypted with AES-256-GCM and the database is sealed to memory.db.enc when the daemon stops. While the vault is unlocked, the FTS index is redacted plaintext (a search tradeoff, not ciphertext).
5. Noise control — ignores noisy apps (for example Slack and Spotify), dedupes focus churn, and summarizes sessions so memory_context stays useful.

Install

Requires Node.js 20+ (22+ preferred for built-in SQLite). As of 14 November 2026 the package is not on the npm registry, so install from the repository. The README’s npx -y ambient-memory commands are the intended path after publish.

git clone https://github.com/JarvisOsorio/ambient-memory.git
cd ambient-memory
npm install
npm test
node ./bin/ambient.js init
node ./bin/ambient.js start --screen auto    # headless: --screen simulated
node ./bin/ambient.js mcp

After the package is published, the same flow is:

npx -y ambient-memory init
npx -y ambient-memory start --screen auto
npx -y ambient-memory mcp

MCP setup (Cursor or Claude Desktop)

The mcp command auto-starts the daemon if needed. From a local clone, point the client at the repo binary (replace the path):

{
  "mcpServers": {
    "ambient-memory": {
      "command": "node",
      "args": ["/ABS/PATH/ambient-memory/bin/ambient.js", "mcp"]
    }
  }
}

Once the package is on npm, the README’s config is:

{
  "mcpServers": {
    "ambient-memory": {
      "command": "npx",
      "args": ["-y", "ambient-memory", "mcp"]
    }
  }
}

MCP tools

• memory_search — full-text search
• memory_recent — recently seen entities
• memory_get — fetch one entity
• memory_context — a “what was I doing” summary
• memory_relate — create or update a relation between entity ids
• memory_status — health and privacy snapshot

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

From the repository, use node ./bin/ambient.js in place of ambient-memory.

Architecture

• Daemon watches Documents, Desktop, Downloads and the current working directory, and indexes screen and browser activity with noise filters.
• Store is SQLite via node:sqlite or sql.js, with FTS5/BM25, field encryption, and seal-on-stop.
• IPC uses a Unix socket at ~/.ambient-memory/ambient.sock, or a Windows named pipe.
• CLI and MCP do not open SQLite directly in normal operation.

Optional overrides: AMBIENT_SQLITE_BACKEND=sql.js forces the WASM backend. --file-key or AMBIENT_FORCE_FILE_KEY=1 forces a file-backed master key instead of the OS keychain.

Privacy and limitations

See SECURITY.md in the repository for the threat model.

Develop

npm install && npm test && npm run demo

Release history: Labs changelog and CHANGELOG.md.