M
MCP Directory CURATED DIRECTORY
911 MCP servers indexed
中文
← Back to directory
S

Soul

Community
The Persistent Memory Layer for Multi-Agent Systems. Give your AI agents a soul that never forgets.
How to install ↓ Compare GitHub source repository ↗
Category
Other #187 of 230
Stars
★ 67 Popular
Transport
stdio (local process)
Runtime
Node.js 18+
Credentials
No credential needed
License
Other / unspecified
Last commit
⚠
Tools
19
44FMRS · D

Soul provides a robust persistent memory solution with deterministic saving and loading to reduce token waste. Its file-based cloud storage approach is simple and vendor-lock-in-free. However, it requires self-managed storage and potential sync issues.

Strongest · Documentation 13/20 Weakest · Reliability 5/20

Reliability
5/20
Security and permissions
8/20
Maintenance
7/20
Documentation
13/20
Setup experience
11/20
Why each score
Reliability 5/20
No evidence in the source that the server starts cleanly and completes MCP handshake; no CI workflow or test execution results are visible in the repository. The README claims 20+ tools, but there is no code-level verification of their parameters and behavior. Error handling and dependency control are insufficiently documented, leading to a low score.
Security and permissions 8/20
No malicious code or credential theft is evident; data is stored in local JSON/SQLite, no remote command execution. However, the permission model is unclear, file ownership operations might be risky, and explicit confirmation for dangerous operations is missing.
Maintenance 7/20
The repository shows recent releases (v9.0) and active commit activity, but zero open issues and no clear security response channel. The license is listed as NOASSERTION on GitHub, while README claims Apache-2.0. Dependency update frequency is unclear.
Documentation 13/20
README is very detailed, with quick start, tool list, configuration, data directory structure, and cloud storage/team sharing examples. However, it lacks a troubleshooting section, full parameter specs for each tool, and error scenarios. The license claim is inconsistent with GitHub metadata.
Setup experience 11/20
Installation steps are clear (npm or from source), with config examples for multiple clients (Cursor, Claude Desktop, Open WebUI, etc.), requiring Node.js 18+. From source, absolute path is needed, and there may be platform differences. No runtime verification in static review, so the setup process is unverified.

Static review · not runListed 2026-08-07

Read the FMRS scoring method →

Fit and risk

What it can accessReads local filesWrites / deletes local filesConnects to a database

Best for

  • AI agents needing persistent memory (e.g., Cursor, VS Code Copilot)
  • Multi-agent orchestration scenarios
  • Developers wanting token efficiency and fast context loading

Not for

  • Simple single-session tasks without need for cross-session memory
  • Data-privacy-critical environments where any syncing is undesirable
  • Users expecting built-in cloud service without self-hosted storage

Required permissions

  • Local filesystem read/write (stores JSON configs, snapshots, ledger)
  • Can point to remote folders via config (e.g., Google Drive)
  • Optional: access to local Ollama service for embeddings

Risks and side effects

  • Data stored as plain JSON, not encrypted for sensitive info
  • Concurrent writes from multiple agents may cause data conflicts (mitigated by file ownership)
  • Cloud sync may introduce inconsistencies due to sync conflicts
  • Requires Node.js 18+

Setup

Before you start

Runtime：Node.js 18+

  1. Install: npm install n2-soul or clone from source and npm install.
  2. Add the server to your MCP configuration: command 'node', args: [absolute path to n2-soul/index.js].
  3. Instruct your agent to call n2_boot at session start and n2_work_end at session end.
  4. Optionally edit lib/config.local.js to enable SQLite backend and Ollama embeddings.
claude_desktop_config.json 
{
  "mcpServers": {
    "soul": {
      "command": "node",
      "args": [
        "/path/to/node_modules/n2-soul/index.js"
      ]
    }
  }
}

Shown for Claude Desktop. Other clients may use a different file or key (VS Code uses "servers") — the configurator below converts it.

.vscode/mcp.json
{
  "servers": {
    "soul": {
      "command": "node",
      "args": [
        "/path/to/node_modules/n2-soul/index.js"
      ]
    }
  }
}

Goes in your project's .vscode/mcp.json (VS Code uses a "servers" key).

Terminal
claude mcp add soul -- node /path/to/node_modules/n2-soul/index.js

Run it in a terminal; replace any <…> placeholders with your own values first.

Generate and validate client config

Check that it works

After adding the server to your MCP config, check that tools like n2_boot and n2_work_end appear in the client's tool list; calling n2_boot(rose, my-app) and getting a boot response (fresh start or loaded handoff) confirms it works.

Troubleshooting

  1. Ensure Node.js >= 18
  2. Verify MCP config path is correct
  3. Ensure data directory is writable
  4. If embeddings enabled, ensure Ollama is running and model pulled

Things to try

Once connected, you can ask your AI assistant things like:

  • Start a session with n2_boot for agent rose on project my-app and load any previous context
  • Save the fact that this project uses the SQLite KV backend to my core memory with n2_core_write
  • Use n2_entity_search to find all service-type entities recorded so far
  • Search past sessions for mentions of the auth module using n2_kv_search

Tools 19

n2_boot read-only
Boot sequence: loads handoff, entities, core memory, agents, and KV-Cache.
n2_work_start writes
Register an active work session.
n2_work_claim writes
Claim file ownership to prevent collisions.
n2_work_log writes
Log file changes during work.
n2_work_end writes
End session: writes ledger, handoff, entities, insights, and KV-Cache.
n2_brain_read read-only
Read from shared memory.
n2_brain_write writes
Write to shared memory.
n2_entity_upsert writes
Add/update entities (auto-merge attributes).
Show 11 more tools
n2_entity_search read-only
Search entities by keyword or type.
n2_core_read read-only
Read agent-specific core memory.
n2_core_write writes
Write to agent-specific core memory.
n2_context_search read-only
Search across brain and ledger.
n2_kv_save writes
Manually save a KV-Cache snapshot.
n2_kv_load read-only
Load the most recent snapshot.
n2_kv_search read-only
Search past sessions by keyword.
n2_kv_gc destructive
Garbage collect old snapshots.
n2_kv_backup writes
Backup to portable SQLite DB.
n2_kv_restore writes
Restore from backup.
n2_kv_backup_list read-only
List backup history.

Use cases

Maintain AI agent context across sessions, avoiding re-explaining
Multi-agent collaboration with seamless handoffs
Track project state, TODOs, and work history
Shared knowledge base for multiple agents to read/write

Supported clients

Claude Desktop
Cursor
VS Code
Open WebUI
LM Studio
Other MCP-compatible hosts

Listed from the project's documentation, not tested by this site.

Overview

Soul is an MCP server that provides AI agents with persistent memory across sessions, handoffs, an immutable work ledger, a shared brain, entity memory (auto-tracks people, hardware, projects), and core memory (agent-specific always-loaded facts). It features high-performance session orchestration with SQLite-based KV-Cache, progressive loading (L1/L2/L3) for token control, and Ebbinghaus forgetting-curve garbage collection. Data is stored in plain JSON files, enabling zero-config cloud storage via any folder-syncing service like Google Drive or NAS.

Similar servers

BioMCP 75 · B

One binary. One grammar. Evidence from the biomedical sources you already trust.

★ 654 · Tools 11 Compare with this →
Compare with other MCP servers

Source revision b58f3fd69c12 Data synced 2026-10-12 Read the FMRS scoring method