Shared Agent Memory MCP

A shared, human-auditable long-term memory service for MCP-compatible coding agents (Cline, OpenCode, Claude Code, GitHub Copilot, Hermes, Antigravity, and others).

Supports configurable authoritative primary storage:

• Notion primary (default): Notion database holds authoritative memory records, with an optional Obsidian Markdown mirror.

• Obsidian primary: Local Markdown files in your Obsidian vault hold authoritative records with zero Notion or network requirements, with an optional Notion remote mirror.

A local SQLite FTS5 index provides fast cached search, with optional local embedding vectors for multilingual semantic and hybrid search.

What works today

• Six MCP tools: memory_search, memory_recent, memory_get, memory_add, memory_update, and memory_delete.

• Configurable primary store via MEMORY_PRIMARY_STORE=notion|obsidian (default: notion).

• Optional opposite-store mirroring via MEMORY_SECONDARY_ENABLED=true|false (default: true).

• Project, agent, category, tag, importance, and provenance metadata.

• A CLI for setup, CRUD, export, cache maintenance, diagnostics, conflict inspection, and sync/watch.

• Idempotent writes with idempotencyKey and local operation journaling.

• Conflict preservation for manually edited Markdown files during synchronization.

• Provider-scoped cache and journal isolation: switching backends automatically treats stale cache entries as invalid.

Storage Modes & Configuration

Set storage engine options in .env or client environment variables:

Copyable Configuration Examples

1. Notion-Only (No local vault or Git required):

MEMORY_PRIMARY_STORE=notion
MEMORY_SECONDARY_ENABLED=false
NOTION_TOKEN=secret_your_notion_token
NOTION_DATABASE_ID=your_notion_database_id

2. Obsidian-Only (Local Markdown only; zero Notion credentials or network calls):

MEMORY_PRIMARY_STORE=obsidian
MEMORY_SECONDARY_ENABLED=false
OBSIDIAN_VAULT_PATH=C:/path/to/your/ObsidianVault

3. Notion Primary with Obsidian Mirror (Default dual-write):

MEMORY_PRIMARY_STORE=notion
MEMORY_SECONDARY_ENABLED=true
NOTION_TOKEN=secret_your_notion_token
NOTION_DATABASE_ID=your_notion_database_id
OBSIDIAN_VAULT_PATH=C:/path/to/your/ObsidianVault

4. Obsidian Primary with Notion Mirror:

MEMORY_PRIMARY_STORE=obsidian
MEMORY_SECONDARY_ENABLED=true
OBSIDIAN_VAULT_PATH=C:/path/to/your/ObsidianVault
NOTION_TOKEN=secret_your_notion_token
NOTION_DATABASE_ID=your_notion_database_id

Search and sync boundaries

memory_search and CLI search default to keyword mode. A fresh SQLite FTS5 cache matching the current primary store handles eligible active-memory keyword queries; requests with unsupported cache filters or a stale cache query the authoritative store instead. After writes, the cache is invalidated until the next sync or cache rebuild.

Set mode to semantic or hybrid in memory_search, or use CLI search --mode semantic|hybrid, to search a fresh local cache with the multilingual MiniLM model. Semantic mode ranks by embedding similarity; hybrid mode combines those results with FTS5 keyword results. The first such query downloads model files to the local model cache and embeds matching cached records. Later queries reuse persisted record vectors and calculate cosine distance with the installed sqlite-vec extension; a changed title or content is re-embedded. Long memories are split into overlapping 1,200-character chunks, and the best matching chunk determines each memory's semantic rank. Semantic results and hybrid results with a vector match include match.excerpt, match.start, and match.end. Run cache rebuild or sync before using these modes.

MCP memory_search and memory_recent accept response: "compact" to omit full content from their results. Compact results include excerpt: the best matching semantic chunk in search (up to 1,200 Unicode characters), a 240-character window around the matching text for keyword-only search, or the first 240 Unicode characters for recent items. The default response: "full" preserves the complete memory shape.

Synchronization & Conflict Handling

Synchronization direction follows the selected authoritative primary store:

• Notion primary: sync and watch copy Notion records to Obsidian.

• Obsidian primary: sync and watch copy Obsidian records to Notion.

If an Obsidian Markdown file was edited after its last sync in Notion-primary mode, the next sync leaves it intact and writes the latest Notion version to a .conflict.md copy. Use conflicts to list these files and resolve <path> --accept-notion or --keep-obsidian to resolve.

In Obsidian-primary mode, Markdown files in memories/<category>/ are the direct authoritative records; manual edits are read directly by the system upon the next query or cache rebuild.

Secondary failures do not undo a successful primary write. If mirroring fails (e.g. temporary network outage), the primary write succeeds and the failure is reported in mirrorError (and obsidian.error).

Recovery lock sidecars (*.takeover.recovery) are never automatically reclaimed. If a crash leaves one behind and writes or mirroring time out, stop every MCP server, CLI, and watcher writing to that vault, back up the vault, and remove only the abandoned recovery sidecar identified for the blocked lock. Restart the clients afterward. Never remove a lock while any writer is running; preserve memory files, pending-move journals, and mirror mappings.

Safe Store Switching

Switching MEMORY_PRIMARY_STORE between notion and obsidian does not implicitly migrate or merge existing data. The SQLite cache is tagged with source_identity and immediately marks records from the previous backend as stale. Run agent-memory cache rebuild or agent-memory sync after switching to populate the cache from the new primary store.

Related MCP server: obsidian-dev-memory

Requirements

• Node.js 22 or newer.

• For Notion primary or mirror: A Notion integration token and target database.

• For Obsidian primary: An explicit, usable local directory path in OBSIDIAN_VAULT_PATH (Git is optional).

Quick start

Install from npm

npm install -g @chaerulcp/shared-agent-memory-mcp

# Option A: Notion primary
$env:MEMORY_PRIMARY_STORE = "notion"
$env:NOTION_TOKEN = "secret_your_notion_token"
$env:NOTION_DATABASE_ID = "your_notion_database_id"

# Option B: Obsidian primary (local only)
$env:MEMORY_PRIMARY_STORE = "obsidian"
$env:MEMORY_SECONDARY_ENABLED = "false"
$env:OBSIDIAN_VAULT_PATH = "C:/path/to/your/ObsidianVault"

agent-memory doctor

Development from source

git clone https://github.com/Chaerulcp/shared-agent-memory-mcp.git
cd shared-agent-memory-mcp
npm ci
npm run build
Copy-Item .env.example .env
node dist/cli.js doctor

The doctor command checks credentials and storage connectivity according to the configured primary store. doctor --sync also checks the optional vault, watcher, and cache.

CLI examples

agent-memory add --title "Use TypeScript for API" --content "The API uses TypeScript." --agent shared --category decision --project backend-service
agent-memory add --title "Retry-safe memory" --content "A durable fact" --idempotency-key task-2026-09-14-001
agent-memory search "TypeScript API" --project backend-service
agent-memory recent --limit 5
agent-memory get YOUR_MEMORY_ID
agent-memory update YOUR_MEMORY_ID --title "Use TypeScript for backend API"
agent-memory delete YOUR_MEMORY_ID
agent-memory cache rebuild
agent-memory cache search "TypeScript"
agent-memory search "cara memperbaiki mobil" --mode semantic --project backend-service
agent-memory search "TypeScript API" --mode hybrid --project backend-service
agent-memory sync --dry-run

delete archives by default; --hard permanently deletes the record. sync --dry-run reads the primary store without modifying cache, files, Git, or remote Notion.

For all commands and accepted flags, run agent-memory --help or node dist/cli.js --help.

MCP client setup

Configure the MCP server in your client configuration:

Notion Primary Configuration:

{
  "command": "notion-memory",
  "args": [],
  "env": {
    "MEMORY_PRIMARY_STORE": "notion",
    "NOTION_TOKEN": "${NOTION_TOKEN}",
    "NOTION_DATABASE_ID": "${NOTION_DATABASE_ID}"
  }
}

Obsidian Primary Configuration (Local-Only):

{
  "command": "notion-memory",
  "args": [],
  "env": {
    "MEMORY_PRIMARY_STORE": "obsidian",
    "MEMORY_SECONDARY_ENABLED": "false",
    "OBSIDIAN_VAULT_PATH": "C:/path/to/your/ObsidianVault"
  }
}

From a source checkout, replace "command": "notion-memory" with "command": "node" and "args": ["C:/path/to/shared-agent-memory-mcp/dist/index.js"].

Setup guides: Claude Code, Codex CLI, OpenCode, Copilot CLI, Cline, Gemini CLI, and other clients.

Validation

npm test

The test suite runs TypeScript build checks and node unit/integration tests covering both Notion and Obsidian storage engines, idempotency, archive lifecycle, cache isolation, and mirror operations.

Contributing and support

See CONTRIBUTING.md, SECURITY.md, and GitHub Issues.

Licensed under the MIT License.