mcp-agents-memory (v0.6.0)

Multi-agent Shared Long-term Memory MCP Server.
An MCP server that enables AI agents (Claude, Gemini, GPT, etc.) to autonomously manage memory and evolve knowledge into validated operational rules (Skills).

🌟 New in v0.6: Knowledge Evolution

• 🧠 Memory Tiering: Intelligent loading strategy mimicking human memory. Full detail for the last 30 days (short-term) and metadata/important summaries for older records (long-term).
• 🦾 Skill Evolution: Repetitive patterns and project know-how automatically evolve into Skills. These rules are injected into the agent's system prompt to guide future actions.
• 🌐 Authority Grounding: High-value facts are reconciled against external authority sources (Tavily for recency, Exa for authority/docs) before storage.
• ⚡ MCP Prompts (Slash Commands): Direct interaction via /briefing, /recall <query>, and /save <text> for a premium UX.
• 🔐 Cross-MCP Ready: Standardized context hooks to share subject_key and session_id with other MCPs (Vision, Audio, etc.).

Features

• 📚 Librarian Engine: Multi-model pipeline (Triage → Extract → Audit) for zero-config fact extraction.
• ⚡ Contradiction Resolution: Detects and updates conflicting information (e.g., "Lives in Seoul" → "Moved to Busan").
• 🧠 Smart Briefing: Dynamic session startup with user profile, project context, and applicable Skills.
• 🔍 Semantic Search: Vector embedding-based retrieval with automatic tier-up for matching long-term memories.
• 🔐 Unified Provenance: Every fact is tagged with author_model, platform, and session_id for perfect traceability.

🧠 Hybrid Intelligence Tech Stack

v0.6 employs a sophisticated multi-role architecture using the best models for each specialized task.

| Role | Technology | Description | |----------|------------|-------------| | Skill Auditor | Anthropic Sonnet / Gemini Pro | Grounding: Reconciles facts with external docs using Tavily + Exa. | | Skill Curator | Google Gemini Flash | Promotion: Monitors memory clusters to identify skill candidates. | | Fact Extractor | OpenAI gpt-4o-mini | Extraction: Efficient atomic fact generation from text. | | Embedding | OpenAI text-embedding-3-small | Standard: 1536-dim vector indexing for semantic search. | | Search (Required) | Tavily + Exa | The Two Pillars: Tavily (Recency) + Exa (Authority/Research). | | Database | PostgreSQL + pgvector | Tiered Storage: Tier-aware partitioning (Short/Long term). |

Architecture

┌─────────────────┐     ┌──────────────┐     ┌──────────────┐
│   Claude Code   │     │   Gemini     │     │     GPT      │
│ (Zero-Config)   │     │ (Autonomous) │     │ (Autonomous) │
└────────┬────────┘     └──────┬───────┘     └──────┬───────┘
         │                     │                    │
         └─────────────────────┼────────────────────┘
                               │
                    ┌──────────▼──────────┐
                    │   MCP Protocol      │
                    │ (w/ instructions)   │  ← Zero-Config Entry
                    └──────────┬──────────┘
                               │
                    ┌──────────▼──────────┐      ┌──────────────────┐
                    │  mcp-agents-memory  │      │  Skill Track     │
                    │  ┌───────────────┐  │ ───▶ │  Curator/Auditor │
                    │  │   Librarian   │  │      │  (Knowledge/Web) │
                    │  │   Engine      │  │      └────────┬─────────┘
                    │  └───────┬───────┘  │               │
                    └──────────┼──────────┘      ┌────────▼─────────┐
                               │                 │   Skills Table   │
                    ┌──────────▼──────────┐      │ (Operational)    │
                    │  PostgreSQL + pgvec │      └──────────────────┘
                    │  (Tiered Memories)  │
                    └─────────────────────┘

Setup

Install

npm i -g mcp-agents-memory

Configure

mcp-agents-memory setup

The interactive wizard:

• Prompts for your Postgres connection (cloud provider with pgvector recommended — Neon and Supabase both have free tiers; URL must end with ?sslmode=require).
• Asks for the required OpenAI key (embeddings).
• Lets you pick a Librarian model preset (see below).
• Writes config to ~/.config/mcp-agents-memory/.env.
• Applies the base schema and runs all migrations idempotently.

Add to your MCP client

Claude Desktop / Claude Code / any MCP-aware client:

{
  "mcpServers": {
    "memory": {
      "command": "mcp-agents-memory",
      "env": {
        "AGENT_KEY": "agent_claude",
        "AGENT_PLATFORM": "claude-code"
      }
    }
  }
}

AGENT_PLATFORM is recorded as the Curator's harness identity on every memory_add call. The Curator's model is captured per-call (defaulting to the Producer's author_model) — set explicitly via the curator_model argument when an orchestrator saves memories on behalf of a different model (e.g. delegating to a subagent). This avoids the staleness that env-static model values would introduce when /model swaps mid-session.

agent_key (optional): Agent persona key for multi-persona harnesses (OpenClaw, Hermes, Opencode). Single-persona setups can ignore — AGENT_KEY env is the default. Applies to memory_add, memory_save_skill, and memory_curator_run.

Cross-machine memory

On a second computer, run npm i -g mcp-agents-memory and mcp-agents-memory setup pointing to the same DATABASE_URL. Memory shares automatically — the database is the source of truth and the MCP server is stateless.

CLI

• mcp-agents-memory — run the MCP server (stdio).
• mcp-agents-memory setup — interactive wizard (writes XDG config, applies schema + migrations).
• mcp-agents-memory migrate — apply pending migrations against an already-configured database.
• mcp-agents-memory help — show help.

Local development

For self-hosted Postgres or working on the codebase directly:

git clone https://github.com/a3lab01create-bit/mcp-agents-memory.git
cd mcp-agents-memory
npm install
npm run build
npm run setup

Config search order: $MEMORY_CONFIG_PATH → ./.env → ~/.config/mcp-agents-memory/.env → <package>/.env. Project-root .env wins for dev workflows.

Requirements

• PostgreSQL ≥ 14 with the pgvector extension.
• Required API key: OpenAI (embeddings).
• Optional API keys: depends on the wizard preset you pick (see below).

Model presets

The wizard offers four presets for the always-on Librarian roles. Every role still accepts <ROLE>_PROVIDER and <ROLE>_MODEL env overrides if you want to mix and match.

| Preset | Triage | Extract | Audit | Contradiction | Required keys | |---|---|---|---|---|---| | Recommended | gemini-2.5-flash-lite | gpt-4o-mini | gpt-4o-mini | gpt-4o-mini | OpenAI + Google | | OpenAI only | gpt-4o-mini | gpt-4o-mini | gpt-4o-mini | gpt-4o-mini | OpenAI | | Anthropic only | claude-haiku-4-5 | claude-haiku-4-5 | claude-haiku-4-5 | claude-haiku-4-5 | Anthropic | | Premium | gemini-2.5-flash | gpt-4o-mini | grok-4.20-0309-reasoning | grok-4.20-0309-reasoning | OpenAI + Google + xAI |

Grounding roles (skill_auditor + memory_auditor) default to claude-sonnet-4-6 and only fire when PROMOTION_ENABLED / MEMORY_AUDIT_ENABLED are on. Sonnet calls use prompt caching automatically — repeat audits within 5 minutes hit at ~10× cheaper rate.

Roadmap

• [x] v0.4 — Librarian Engine (Auto extraction + resolution)
• [x] v0.5 — Provenance Layer (Model/Platform tracking)
• [x] v0.6 — Knowledge Evolution: Tiered Memory + Skill Grounding
• [x] v4.5 — Skill System closure (Curator + Auditor + Promotion + Injector filtering)
• [x] v5.0 — Memory Graph + External Knowledge Grounding + Auto Forgetting + memory_restore
• [x] Connectors v1: Notion page ingestion (connector_sync MCP tool)
• [ ] Connectors v2: Notion database iteration, GitHub, Drive
• [ ] v1.0 — Production Ready: Full benchmark and stability

Credits

Built by Hoon (triplealab) in collaboration with Claude (Anthropic) and Codex (OpenAI). Most of v0.5 / v0.6 / v4.5 / v5.0 was designed and implemented through iterative human-AI pair programming — eating our own dog food on the same memory and skill systems this server provides.

License

MIT