1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@agoya Remember that my preferred port is 3000." That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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

Related MCP server: junto-memory

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

This server cannot be installed

F

license - not found

-

quality - not tested

A

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

–Release cycle

1Releases (12mo)

Commit activity

Resources

GitHub Repository

Need Help?

Related Servers

agoya