Allows storing AI memory data in Google Drive for persistent cross-session memory, enabling automatic sync without API keys.
Provides semantic search capability by using Ollama embeddings (e.g., nomic-embed-text) for context-aware memory retrieval.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Soul boot my agent 'helper' for project 'myapp'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Save what you worked on with an AI and what comes next, so a later conversation can pick it up.
Save what you worked on with an AI and what comes next, so a later conversation can pick it up.
A story illustrating the feature, rather than a screenshot of the app.
Use it for work that spans several days, or when each new conversation needs the same background explained again.
Your AI app needs an MCP connection. MCP lets an AI app call external tools. Configure the app or agent to actually call the save and restore tools.
Related MCP server: Mnemexa MCP
Run node --version in a terminal and check for Node.js 22 or later. These commands create a fresh practice folder and install the GitHub release. Keep the example file and database in this folder.
mkdir soul-demo
cd soul-demo
npm init -y
npm install https://github.com/choihyunsus/soul/releases/download/v9.2.1/n2-soul-9.2.1.tgzIf installation reports a SQLite build error, you may need your platform’s C/C++ build tools. See the installation reference for platform requirements.
Add this connection to your AI app’s MCP settings. Replace C:/tools/soul with the absolute path of your install folder. N2_DATA_DIR is a separate folder for memories. On macOS or Linux, use your own path such as /home/me/tools/soul.
{
"mcpServers": {
"soul": {
"command": "node",
"args": [
"C:/tools/soul/node_modules/n2-soul/dist/index.js"
],
"env": {
"N2_DATA_DIR": "C:/agent-memory/soul"
}
}
}
}Enable the connection, then ask your AI to do the following.
Call Soul’s n2_kv_save with agent assistant, project demo, and summary “Review the installation guide next time”. After a successful save, call n2_kv_load with the same agent and project to read it back.
Look for a saved ID and the same next step in the loaded text. Check the actual tool results. Use the same identity and project in later conversations.
Soul keeps progress summaries and handoffs. Mimir retrieves experience, Gumiho coordinates role-based work, and Loom handles dialogue and tool use. Connect the capabilities your app needs.
The full reference covers app integration, APIs, supported features, recovery and validation. The release page contains the installable version and release notes.
A few terms used in the reference: MCP connects tools to an AI app, a database stores records, and the host is the app that connects and runs this module.
Review the license for use and redistribution. Dependencies can have their own terms, including commercial-use conditions described in the reference.
Boot sequence — loads soul-board handoff, entity/core memory, agent list, and KV-Cache context.
Inputs: agent (required), project.
Read a file from shared memory (data/memory/). Agents share information here.
Inputs: filename (required).
Write a file to shared memory (data/memory/). Share information between agents.
Inputs: content (required), filename (required).
Search across Brain memory and Ledger entries for relevant past context. Uses keyword matching with recency weighting.
Inputs: query (required), sources, semantic, maxResults.
Read agent-specific core memory. Core memory is always loaded at boot for context injection.
Inputs: agent (required).
Write to agent-specific core memory. Stored permanently, injected at every boot.
Inputs: key (required), agent (required), value (required).
Search entities by keyword or type. Returns matching entities with attributes.
Inputs: type, query.
Add or update entities (person, hardware, project, concept). Auto-merges attributes if entity exists.
Inputs: entities (required).
Backup KV-Cache data to a portable SQLite DB. Supports incremental backups.
Inputs: project (required), full.
List KV-Cache backup history for a project.
Inputs: project (required).
Remove old KV-Cache snapshots. Uses config defaults if no args.
Inputs: project (required), maxAgeDays.
Load the most recent KV-Cache snapshot for a project. Returns compressed context.
Inputs: project (required), agent, level, budget.
Restore KV-Cache data from a backup DB.
Inputs: project (required), target, backupId.
Save a durable checkpoint during work or before replying. does not finish active work.
Inputs: agent (required), project (required), summary (required), todo, +4 more.
Read relevant historical snapshots for one project and agent (defaults to boot identity). Bounded lexical matching with domain aliases and correction precedence; source IDs and matched excerpts, no semantic-only ranking.
Inputs: query (required), project (required), agent, maxResults.
Record application evidence from data/evidence//. Requires soul-evidence/v1 JSON, matching lesson/work identity, completed durable work, method, observation, outcome and applied flag. Checks provenance/integrity, not the truth of authored observations.
Inputs: project (required), artifact (required), lessonId (required), requestId (required), +2 more.
Create a dormant lesson candidate with source experience IDs. No automatic promotion.
Inputs: project (required), requestId (required), sourceIds (required), description (required), +1 more.
Promote only after two distinct completed-work positive applied results, >=80% positive, no negative result, unchanged sources/artifacts and review of all current user corrections. Hold/retire retain history. Supersession is atomic; no executable rules are created.
Inputs: action (required), reason (required), project (required), lessonId (required), +4 more.
Inspect scoped lesson state, recorded evidence, correction IDs and review history. Legacy insights are not implicitly verified.
Inputs: project (required), agent, lessonId.
Read historical reports and reviewed lessons for one project and agent; no learning mutations.
Inputs: project (required), agent, query.
Append one reported study entry idempotently. Outcome/type are reports, not verified effects or user authority.
Inputs: action (required), entryId (required), outcome (required), project (required), +4 more.
Freeze and save study reports. Restart-safe retry; no digest, cross-project merge, voting or graduation.
Inputs: project (required), sessionId (required), agent.
Find unfinished durable study collections in one scope.
Inputs: project (required), agent.
Start durable scoped study collection. Returns a sessionId; same-topic sessions stay separate.
Inputs: topic (required), project (required), requestId (required), agent, +1 more.
Claim file ownership before modifying. Prevents collision with other agents.
Inputs: agent (required), intent (required), project (required), filePath (required).
End work sequence. Writes immutable ledger entry, updates soul-board handoff, releases file ownership.
Inputs: agent (required), title (required), project (required), summary (required), +5 more.
Log file changes during work. Reports created/modified/deleted files with descriptions.
Inputs: project (required), agent, decisions, sessionId, +3 more.
List unfinished work and completed work with pending Mimir collection; use the exact sessionId to resume.
Inputs: project.
Start a work sequence. Registers agent in activeWork on soul-board.
Inputs: task (required), agent (required), project (required).
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 29 tools
Most tools target distinct subsystems (work lifecycle, brain memory, core memory, entities, KV cache, Mimir study/lessons), but there are several similarly purposed retrieval tools: context_search, kv_search, kv_load, mimir_recall, and entity_search. Descriptions do differentiate them, but an agent must read carefully to pick the right search/recall surface.
Names consistently use an n2_ prefix and snake_case, generally following n2_<domain>_<operation> (e.g. n2_work_start, n2_kv_save, n2_mimir_lesson_review). Minor deviations exist where tools are noun-like rather than verb-led (n2_work_sessions, n2_mimir_lessons, n2_boot), but the overall pattern remains predictable.
The server is large at 29 tools, but it spans several real subsystems rather than duplicating a single workflow. Each subsystem has a small coherent set, though the total surface is heavy enough to increase selection burden.
Core lifecycle coverage is strong for work sessions, KV snapshots, and Mimir studies/lessons, but shared memory and entity management lack delete/list operations and there is no general brain file listing. These are notable gaps, though agents can work around many of them via search and overwrite-style writes.
Persistent memory for AI agents: save, search and connect context across tools and sessions.
Memory for AI agent teams across tools, sessions, repositories, and teammates.
Persistent memory and knowledge graphs for AI agents. Hybrid search, context checkpoints, and more.
Shared memory for teams: every AI agent works from your company's knowledge, decisions and history.
