# Unified Memory MCP

Local, explicit memory vault exposed as an MCP server. It is meant to give Codex, ChatGPT Apps, and your own agent clients a shared memory layer without relying on private product memory crossing surfaces automatically.

## What It Does

- Stores memories in `~/.unified-memory-mcp/memories.json`.
- Writes a minimal audit log to `~/.unified-memory-mcp/events.jsonl`.
- Exposes MCP tools over stdio.
- Hides `sensitive: true` memories from default read/search/list calls.
- Keeps the storage format human-readable and easy to back up or inspect.

## Tools

- `remember`: create a memory.
- `search_memory`: search active memories by text and filters.
- `list_memories`: list recent memories.
- `get_memory`: fetch a memory by id.
- `update_memory`: patch an existing memory.
- `forget_memory`: hard-delete a memory.
- `memory_stats`: show vault paths and aggregate counts.

## Memory Shape

```json
{
  "id": "mem_...",
  "type": "preference",
  "scope": "personal",
  "namespace": "default",
  "content": "Prefer pnpm over npm for JavaScript projects.",
  "tags": ["javascript", "package-manager"],
  "source": "manual",
  "confidence": 0.8,
  "sensitive": false,
  "created_at": "2026-07-04T00:00:00.000Z",
  "updated_at": "2026-07-04T00:00:00.000Z",
  "expires_at": null,
  "metadata": {}
}
```

Allowed `type` values: `preference`, `project`, `workflow`, `fact`, `decision`, `context`, `rule`.

Allowed `scope` values: `personal`, `company`, `repo`, `project`, `global`.

## Local Usage

```bash
cd /Users/yoshikondo/unified-memory-mcp
npm test
npm run smoke
npm run smoke:http
```

Run the MCP server directly:

```bash
MEMORY_MCP_HOME=/Users/yoshikondo/.unified-memory-mcp node /Users/yoshikondo/unified-memory-mcp/src/server.js
```

Run the optional Streamable HTTP MCP server:

```bash
MEMORY_MCP_HOME=/Users/yoshikondo/.unified-memory-mcp \
MEMORY_MCP_HOST=127.0.0.1 \
MEMORY_MCP_PORT=3199 \
npm run http
```

The HTTP endpoint is `http://127.0.0.1:3199/mcp`; health is available at `http://127.0.0.1:3199/health`.

If you bind to anything other than localhost, set `MEMORY_MCP_TOKEN` and put the service behind HTTPS before connecting remote clients.

## Codex Setup

Add this to `~/.codex/config.toml`:

```toml
[mcp_servers.unified_memory]
command = "node"
args = ["/Users/yoshikondo/unified-memory-mcp/src/server.js"]
startup_timeout_sec = 10
tool_timeout_sec = 30

[mcp_servers.unified_memory.env]
MEMORY_MCP_HOME = "/Users/yoshikondo/.unified-memory-mcp"
```

Restart Codex after changing MCP config.

## Privacy Notes

Do not store secrets, credentials, private keys, API tokens, or raw sensitive personal data. Mark entries `sensitive: true` only as an extra visibility guard; it is not encryption.

This is separate from built-in ChatGPT memory and Codex memory. It is an explicit source of truth that clients can connect to through MCP.

For ChatGPT, this is the backend MCP surface. You still need a ChatGPT App or remote MCP deployment with HTTPS and appropriate auth before ChatGPT web can use it.