Agoya

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

Persistent memory layer that AI coding agents (Claude Code, Codex, OpenCode, agy, Clew) connect to via MCP. No database, no external service — just JSON files under .agoya/.

Install

npm install -g agoya

Or run directly:

npx agoya

Usage

Run as MCP server (stdio)

agoya
# or with custom root:
AGOYA_ROOT_DIR=/path/to/project agoya

Register in Claude Code

claude mcp add agoya -- /path/to/agoya/dist/index.js

Or add to .mcp.json:

{
  "mcpServers": {
    "agoya": {
      "command": "node",
      "args": ["/path/to/agoya/dist/index.js"]
    }
  }
}

Register in Codex

Add to Codex MCP config pointing to the same path.

HTTP transport (multi-agent hub)

AGOYA_TRANSPORT=http AGOYA_PORT=8765 agoya

Then register each agent:

claude mcp add --transport http agoya http://localhost:8765/mcp

Add bearer auth for shared networks:

AGOYA_HTTP_TOKEN=your-secret AGOYA_TRANSPORT=http AGOYA_PORT=8765 agoya

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 across all memories with BM25 keyword ranking
get_memory	Retrieve a single memory by ID and type
list_memories	List memories with optional type/agent/tag filters
forget	Permanently delete a memory by ID
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
agoya://memories	All stored memories
agoya://memories/{type}	Memories filtered by type
agoya://stats	Memory statistics
agoya://sessions	Currently connected agent sessions

On-disk layout

<root>/.agoya/
├── config.json         # Server configuration
├── index.json          # Search index (id → metadata)
├── facts/              # Permanent knowledge
├── insights/           # Lessons learned
├── chunks/             # Conversation snapshots
└── working/            # Session scratchpads

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, requires model download)

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 vector search:

AGOYA_DISABLE_VECTORS=1 agoya

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" }]

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

Configuration

Env var	Default	Description
AGOYA_ROOT_DIR	process.cwd()	Root directory for .agoya/ store
AGOYA_DISABLE_VECTORS	false	Set to 1 to disable vector embeddings + semantic search
AGOYA_TRANSPORT	stdio	Transport: stdio or http/streamable
AGOYA_HOST	0.0.0.0	HTTP bind host
AGOYA_PORT	8765	HTTP port
AGOYA_HTTP_TOKEN	—	Bearer token required on /mcp

Build

npm run build        # TypeScript → dist/
npm run dev          # Run via tsx (dev mode)
npm start            # Run compiled version
npm test             # Run tests