Agoya - Agent Memory

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