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
S
Soul
Community
The Persistent Memory Layer for Multi-Agent Systems. Give your AI agents a soul that never forgets.
GitHub source repository ↗
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.
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.
Tools
n2_boot
Boot sequence: loads handoff, entities, core memory, agents, and KV-Cache.
n2_work_start
Register an active work session.
n2_work_claim
Claim file ownership to prevent collisions.
n2_work_log
Log file changes during work.
n2_work_end
End session: writes ledger, handoff, entities, insights, and KV-Cache.
n2_brain_read
Read from shared memory.
n2_brain_write
Write to shared memory.
n2_entity_upsert
Add/update entities (auto-merge attributes).
n2_entity_search
Search entities by keyword or type.
n2_core_read
Read agent-specific core memory.
n2_core_write
Write to agent-specific core memory.
n2_context_search
Search across brain and ledger.
n2_kv_save
Manually save a KV-Cache snapshot.
n2_kv_load
Load the most recent snapshot.
n2_kv_search
Search past sessions by keyword.
n2_kv_gc
Garbage collect old snapshots.
n2_kv_backup
Backup to portable SQLite DB.
n2_kv_restore
Restore from backup.
n2_kv_backup_list
List backup history.
Setup
- Install: npm install n2-soul or clone from source and npm install.
- Add the server to your MCP configuration: command 'node', args: [absolute path to n2-soul/index.js].
- Instruct your agent to call n2_boot at session start and n2_work_end at session end.
- 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"
]
}
}
}
Fit and risk
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+
Troubleshooting
- Ensure Node.js >= 18
- Verify MCP config path is correct
- Ensure data directory is writable
- If embeddings enabled, ensure Ollama is running and model pulled
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 DesktopFull support
CursorFull support
VS Code CopilotFull support
Open WebUIFull support
LM StudioFull support
Other MCP-compatible hostsFull support