# Fovea Memory MCP

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:

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

The equivalent command is:

```bash
npx -y fovea-memory-mcp@1
```

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

```text
~/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

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

### Codex

```bash
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:

```json
{
  "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

```bash
npm test
```

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

## License

Apache-2.0