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

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

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

Run the MCP server directly:

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

Run the optional Streamable HTTP MCP server:

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:

[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.