Oracle Memory

File-backed Memory MCP Server for multi-agent coordination.

Persistent memory layer for AI coding agents.
No database — just JSON files under .oracle-memory/.
Agents connect via stdio, HTTP, or streamable transport.

Requirements

• Node.js 24+

Quick start

npm install -g oracle-memory

# Run as MCP server (stdio)
oracle-memory

# Or with custom root:
ORACLE_MEMORY_ROOT_DIR=/path/to/project oracle-memory

Register in Claude Code:

claude mcp add oracle-memory -- /path/to/oracle-memory/dist/index.js

Register in Codex

Add to Codex MCP config pointing to the same path.

Memory types

Type	Purpose	Lifetime
fact	Permanent knowledge (preferences, decisions, conventions)	Forever
insight	Lessons learned, gotchas, discoveries	Forever
chunk	Conversation snapshots (pre-compact)	Auto-expire (configurable TTL)
working	Session scratchpad, temporary context	Cleared between sessions

MCP tools

Tool	Description
remember	Save a fact/insight/chunk/working memory
recall	Search with hybrid BM25 + vector + entity graph ranking
get_memory	Retrieve a single memory by ID and type
update_memory	Update content/tags/importance/meta/TTL of an existing memory
list_memories	List memories with optional type/agent/tag/query filters
forget	Permanently delete a memory by ID and type
clear_working	Clear working memory for an agent (or all)
consolidate	Merge similar memories by tag overlap
get_sessions	List currently connected agent sessions
get_stats	Memory statistics by type and agent

MCP resources

URI	Content
oracle-memory://memories	All stored memories
oracle-memory://memories/{type}	Memories filtered by type
oracle-memory://stats	Memory statistics
oracle-memory://sessions	Currently connected agent sessions

HTTP transport (multi-agent hub)

ORACLE_MEMORY_TRANSPORT=http ORACLE_MEMORY_PORT=8765 oracle-memory

Register each agent:

claude mcp add --transport http oracle-memory http://localhost:8765/mcp

With bearer auth:

ORACLE_MEMORY_HTTP_TOKEN=your-secret ORACLE_MEMORY_TRANSPORT=http ORACLE_MEMORY_PORT=8765 oracle-memory

Backward compatibility: Old AGOYA_* env vars still work as fallbacks.

Storage layout

<root>/.oracle-memory/
├── config.json         # Server configuration
├── facts/              # Permanent knowledge
├── insights/           # Lessons learned
├── chunks/             # Conversation snapshots
├── working/            # Session scratchpads
├── graph/graph.json    # Entity relationship graph
└── vectors/            # Vector embeddings (optional)

All writes are atomic (write .tmp → rename). No corruption from crashes.

Search

BM25 keyword search (built-in, zero deps)

Tokenization + stop word filtering + BM25 ranking. Fast, deterministic, works offline.

Vector semantic search (optional)

When enabled, remember also indexes each memory with a vector embedding using Xenova/all-MiniLM-L6-v2 (384-dim). On recall, results are fused using RRF (Reciprocal Rank Fusion) — combining keyword relevance with semantic similarity for the best of both worlds.

The model (~15MB) auto-downloads on first use and caches locally.

To disable:

ORACLE_MEMORY_DISABLE_VECTORS=1 oracle-memory

Example workflow

# Agent saves knowledge
→ remember(agent="claude", type="fact", content="Project uses port 3000", tags=["config"])

# Agent searches across sessions
→ recall(query="port configuration")
← [{ entry: { content: "Project uses port 3000", ... }, score: 2.3, method: "bm25" }]

# Update a memory
→ update_memory(id="20260713-...", type="fact", { content: "Project uses port 4000" })

# Check memory stats
→ get_stats()
← { totalMemories: 42, byType: { fact: 20, insight: 10, chunk: 10, working: 2 }, ... }

Environment

Variable	Default	Description
ORACLE_MEMORY_ROOT_DIR	cwd	Root directory for .oracle-memory/ store
ORACLE_MEMORY_DISABLE_VECTORS	false	Set to 1 to disable vector search
ORACLE_MEMORY_TRANSPORT	stdio	Transport: stdio or http/streamable
ORACLE_MEMORY_HOST	0.0.0.0	HTTP bind host
ORACLE_MEMORY_PORT	8765	HTTP port
ORACLE_MEMORY_HTTP_TOKEN	—	Bearer token for /mcp
ORACLE_MEMORY_LOG_LEVEL	info	Log level

Old AGOYA_* env vars still work as fallbacks.

Build

npm run build        # TypeScript → dist/
npm run check        # Type-check only
npm run dev          # Run via tsx
npm start            # Run compiled version
npm test             # Run tests

Integrated projects

Oracle-Memory writes .oracle-memory/ format natively, making it interoperable with:

• Oracle — MCP-powered AI coding consultant (skills + oracles)
• Oracle Messages — Multi-agent message bus