Fovea Memory

Fovea Memory MCP is a local stdio MCP server that lets AI clients read memories created by the Fovea macOS app.

It runs on your Mac, reads the local Fovea Memory SQLite database, and exposes only memories marked visible to MCP. It does not upload your memory database to Fovea, GitHub, npm, or any third-party service.

Install

Use this configuration in any MCP client that supports local stdio servers:

{
  "mcpServers": {
    "fovea-memory": {
      "command": "npx",
      "args": ["-y", "fovea-memory-mcp@1"]
    }
  }
}

The equivalent command is:

npx -y fovea-memory-mcp@1

No environment variables are required for normal use. The server discovers the current Fovea namespace through:

~/Library/Application Support/Fovea/current-namespace.json

Requirements

• macOS with Fovea installed and run at least once
• Node.js 22.5 or newer
• A local Fovea Memory database with memories visible to MCP
• An MCP client that supports local stdio servers

Client Examples

Claude Code

claude mcp add fovea-memory -- npx -y fovea-memory-mcp@1

Codex

codex mcp add fovea-memory -- npx -y fovea-memory-mcp@1

Claude Desktop, Cursor, VS Code, and Other Clients

Use the standard local server configuration:

{
  "mcpServers": {
    "fovea-memory": {
      "command": "npx",
      "args": ["-y", "fovea-memory-mcp@1"]
    }
  }
}

Some clients use a different top-level key, such as servers instead of mcpServers. Keep the server command and args the same.

Tools

The server exposes these MCP tools:

• recall_recent_fovea_memory: recall what the user recently saw, asked, or said through Fovea
• list_recent_fovea_memories: list recent visible Fovea memories
• search_fovea_memory: search visible Fovea memories by keyword, with optional semantic search when configured. Optional filters include from_epoch, to_epoch, time_expression (自然语言时间词，如「昨天」「上周」「今天上午」「this morning」；explicit epochs take precedence), source_type, include_hidden, and limit.
• forget_fovea_memory: soft-delete a memory from the local recent store

Privacy Model

• Local stdio process only
• Reads the local Fovea Memory SQLite database
• Returns only active memories with mcp_visibility='visible'
• Soft delete uses local SQLite status updates
• Writes best-effort local audit events to audit.sqlite
• Does not send memory data to GitHub or npm

Semantic search is optional. If FOVEA_BACKEND_URL and FOVEA_AUTH_TOKEN are set, the server can request an embedding for the search query. If they are not set, search automatically falls back to local keyword matching.

Development

npm test

The test suite creates a synthetic SQLite database at runtime. It does not require private Fovea fixtures.

License

Apache-2.0