Content
# 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
```bash
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:
```bash
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)
```bash
ORACLE_MEMORY_TRANSPORT=http ORACLE_MEMORY_PORT=8765 oracle-memory
```
Register each agent:
```bash
claude mcp add --transport http oracle-memory http://localhost:8765/mcp
```
With bearer auth:
```bash
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:
```bash
ORACLE_MEMORY_DISABLE_VECTORS=1 oracle-memory
```
## Example workflow
```bash
# 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
```bash
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](https://github.com/JonusNattapong/Oracle) — MCP-powered AI coding consultant (skills + oracles)
- [Oracle Messages](https://github.com/JonusNattapong/oracle-messages) — Multi-agent message bus
