Multi-Agent Memory MCP

Local-first, model-agnostic memory for coding agents and local LLM systems.

This repository provides persistent memory and bounded graph retrieval through MCP. Version 0.2.0 combines trust-weighted FTS5, scope concepts, hashed features, optional local vectors, and graph paths. It has no hosted service, telemetry, or account.

Existing users: follow the 0.2 upgrade guide. The database format stays at version 1. Local vectors require an explicit setup step.

Use the same memory store with Claude Code, Codex, OpenCode, or a custom MCP client. OpenCode examples connect Llama-family and other local models through Ollama, LM Studio, vLLM, and OpenAI-compatible APIs.

The setup and test matrix supports Windows, macOS, and Linux.

Measured result

The original benchmark uses 400 synthetic questions and 350 decoy records. The following table reports the legacy retrieval API. It includes direct, one-hop, two-hop, and negative cases.

Configuration	Recall@5	MRR	Direct	One hop	Two hops	Negative abstention	Decoy contamination
Lexical only	0.3333	0.3333	1.0000	0.0000	0.0000	1.0000	0.0000
One hop, 0.3 decay	0.6667	0.5000	1.0000	1.0000	0.0000	1.0000	0.0000
Two hops, 0.3 decay	1.0000	0.6111	1.0000	1.0000	1.0000	1.0000	0.0000

This is the strongest memory configuration tested on this fixture family. It is not a universal optimum.

An earlier private pilot used a separate multi-agent tiered system. Direct Recall@5 stayed at 0.92. Link-only Recall@5 rose from 0.00 to 0.27. A 350-decoy run reached 0.19. This repository contains no pilot records, names, prompts, or private data.

Run the public benchmark:

npm run build
npm run benchmark
node scripts/check-benchmark.mjs
npm run benchmark:meta

See benchmark/results.json and docs/benchmark.md.

Install

Requirements:

• Node.js 22 or newer.
• Git.
• A local MCP client for agent use.

Clone the repository:

git clone https://github.com/jhunter11/multi-agent-memory-MCP.git
cd multi-agent-memory-MCP

Windows PowerShell:

powershell -ExecutionPolicy Bypass -File scripts/setup.ps1

macOS or Linux:

chmod +x scripts/setup.sh
./scripts/setup.sh

The default setup verifies the package and changes no client configuration.

Configure a coding agent

The renderer uses three absolute paths:

1. The current Node executable.
2. The built MCP server.
3. The SQLite database.

Print a client configuration on Windows:

scripts/setup.ps1 -Client claude-code -SkipInstall
scripts/setup.ps1 -Client codex -SkipInstall
scripts/setup.ps1 -Client opencode -SkipInstall

Print a client configuration on macOS or Linux:

./scripts/setup.sh --client claude-code --skip-install
./scripts/setup.sh --client codex --skip-install
./scripts/setup.sh --client opencode --skip-install

Add -Configure or --configure to write a configuration. The script backs up an existing file. It preserves unrelated settings. It refuses a duplicate server unless you also pass the replacement option.

Checked examples:

• Claude Code .mcp.json
• Codex config.toml
• OpenCode opencode.json

See docs/clients.md for exact CLI commands and paths.

Use Ollama, Llama, LM Studio, or vLLM

Your coding agent or MCP host calls the answer model and the memory tools. Memory can use an optional local embedding model. It never sends memories to a hosted model.

Full OpenCode examples:

• Ollama and Llama
• LM Studio
• vLLM
• Generic OpenAI-compatible API

The selected model must support structured tool calls. A compatible HTTP endpoint alone does not give a model tool-use skills.

See docs/local-models.md.

How retrieval works

The default MCP strategy is meta:

query
  -> FTS5 + optional local MiniLM vectors
  -> trust-weighted fusion + scope concepts + hashed token features
  -> exact identifier routing when lexical evidence is narrow
  -> typed graph expansion, maximum two hops
  -> weakest-path trust, ordinary decay 0.3, conflict decay 0.9
  -> whole source records in a bounded JSON evidence packet

Linked records can add context when they do not repeat the query terms. Cycles terminate, and the engine keeps one best path per record. Scores and trust ratings are not truth probabilities.

The packet includes source dates, body hashes, paths, and conflict links. It marks missing support as unknown and grants no permission to act. See retrieval and handoff details.

Scopes are organization and ranking labels. They are not access-control boundaries. Use this release in a trusted, single-user local environment.

MCP tools

Tool	Purpose
memory_write	Store a fact, decision, observation, or procedure.
memory_search	Run lexical search with filters.
memory_recall	Build bounded task context with graph expansion.
memory_relate	Add a typed edge between records.
memory_neighbors	Inspect linked records and edge direction.
memory_feedback	Adjust trust without deleting history.
memory_reflect	Store a supplied synthesis and link its sources.
memory_export	Write a confined JSONL snapshot.
memory_stats	Show record, edge, feedback, and scope counts.

Meta recall returns the same JSON packet as text and structured content. Other tools return short text and structured content. The server supports both MCP protocol eras already tested by this project.

TypeScript API

The storage and retrieval core does not depend on MCP:

import { createStore } from 'multi-agent-memory-mcp';

const store = createStore('/absolute/path/to/memory.sqlite');
const entry = store.write({
  kind: 'decision',
  scope: 'team/engineering',
  title: 'Keep snapshots outside Git',
  body: 'Export plaintext JSONL to a private data directory.',
  source: 'architecture review'
});

const result = await store.recallMeta({
  task: 'prepare the next architecture review',
  entryScope: 'team/engineering',
  maxHops: 2,
  graphDecay: 0.3
});

store.close();

Data safety

The live SQLite file stays on one local filesystem. Do not put it in Dropbox, Google Drive, OneDrive, iCloud, or a network share.

Use JSONL export and import to move data. Exports contain plaintext memory. Store them outside source control and protect them like the source material.

The repository ignores SQLite, database, JSONL, snapshot, backup, and generated client files by default.

See docs/privacy.md and docs/troubleshooting.md.

Development

npm ci
npm run typecheck
npm test
npm run build
npm run probe
npm run benchmark
npm run verify

GitHub Actions runs the release gate on Windows, macOS, and Ubuntu.

License

MIT. See LICENSE.