한국어

Soul

Your AI agent forgets everything when a session ends. Soul fixes that.

Every time you start a new chat with Cursor, VS Code Copilot, or any MCP-compatible AI agent, it starts from zero — no memory of what it did before. Soul is an MCP server that gives your agents:

• Persistent memory that survives across sessions
• Handoffs so one agent can pick up where another left off
• Work history recorded as an immutable log
• Shared brain so multiple agents can read/write the same context
• Entity Memory — auto-tracks people, hardware, projects
• Core Memory — agent-specific always-loaded facts

Works great with the N2 ecosystem: Ark (AI safety) · Arachne (code context) · QLN (tool routing)

Soul is one small component of N2 Browser — an AI-native browser we're building. Multi-agent orchestration, real-time tool routing, inter-agent communication, and much more are currently in testing. This is just the beginning.

Table of Contents

• What's New in v9.0
• Quick Start
• Why Soul?
• Features
• Cloud Storage
• Available Tools
• Configuration
• Contributing
• Changelog

What's New in v9.0

Strict TypeScript — Zero any, zero memory leaks, automated quality enforcement.

Full TypeScript Strict Mode

• Source code migrated to TypeScript with strict: true
• Zero any — every type is explicit and verifiable
• ESLint strictTypeChecked rules catch floating promises, type safety violations
• 30 unit tests with npm run verify one-command pipeline

Security & Memory Audit

• WASM memory leak fix — stmt.free() wrapped in try/finally
• Silent error swallowing eliminated — all .catch() handlers log errors
• HTTP response size limits for embedding requests
• dispose() methods for proper timer cleanup

v8.0 Features (Included)

• Forgetting Curve GC — intelligent memory retention based on access patterns
• Async I/O — non-blocking operations, 42% faster KV load
• 3-tier memory — Hot → Warm → Cold lifecycle

See CHANGELOG.md for full version history.

---

Quick Start

1. Install

Option A: npm (recommended)

npm install n2-soul

Option B: From source

git clone https://github.com/choihyunsus/soul.git
cd soul
npm install

2. Add Soul to your MCP config

Soul is a standard MCP server (stdio). Add it to your host's config:

<details> <summary><strong>Cursor / VS Code Copilot / Claude Desktop</strong></summary>

Add to mcp.json, settings.json, or claude_desktop_config.json:

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

</details> <details> <summary><strong>Ollama + Open WebUI</strong></summary>

Open WebUI supports MCP tools natively.

# 1. Make sure Ollama is running
ollama serve

# 2. Install Soul
npm install n2-soul

# 3. Find your Soul path
# Windows:
echo %cd%\node_modules\n2-soul\index.js
# Mac/Linux:
echo $(pwd)/node_modules/n2-soul/index.js

In Open WebUI: Go to Settings → Tools → MCP Servers → Add new server:

Name: soul
Command: node
Args: /your/path/to/node_modules/n2-soul/index.js

Now any model you chat with in Open WebUI can use Soul's 20+ memory tools.

</details> <details> <summary><strong>LM Studio</strong></summary>

LM Studio supports MCP natively. Add to ~/.lmstudio/mcp.json:

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

</details> <details> <summary><strong>Any other MCP-compatible host</strong></summary>

Soul speaks standard MCP protocol over stdio. If your tool supports MCP, Soul works. Just point the command to node and the args to n2-soul/index.js.

</details>

Tip: If you installed via npm, the path is node_modules/n2-soul/index.js. If from source, use the absolute path to your cloned directory.

3. Tell your agent to use Soul

Add this to your agent's rules file (.md, .cursorrules, system prompt, etc.):

## Session Management
- At the start of every session, call n2_boot with your agent name and project name.
- At the end of every session, call n2_work_end with a summary and TODO list.

That's it. Two commands your agent needs to know:

| Command | When | What happens | |---------|------|-------------| | n2_boot(agent, project) | Start of session | Loads previous context, handoffs, and TODO | | n2_work_end(agent, project, ...) | End of session | Saves everything for next time |

Next session, your agent picks up exactly where it left off — like it never forgot.

Requirements

• Node.js 18+

Why Soul?

| Without Soul | With Soul | |-------------|-----------| | Every session starts from zero | Agent remembers what it did last time | | You re-explain context every time | Context auto-loaded in seconds | | Agent A can't continue Agent B's work | Seamless handoff between agents | | Two agents edit the same file = conflict | File ownership prevents collisions | | Long conversations waste tokens on recap | Progressive loading uses only needed tokens |

Core Architecture

| Feature | Soul | |---|:---:| | Storage | Deterministic (JSON/SQLite) | | Loading | Mandatory (code-enforced at boot) | | Saving | Mandatory (force-write at session end) | | Validation | Rust compiler (n2c) | | Multi-agent | Built-in handoffs + file ownership | | Token control | Progressive L1/L2/L3 (~500 tokens min) | | Dependencies | 3 packages |

Key difference: Soul is deterministic — the code forces saves and loads. The LLM does not decide what to remember, preventing accidental "forgetting".

Token Efficiency

Soul dramatically reduces token waste from context re-explanation:

| Scenario | Tokens per session start | |----------|--------------------------| | Without Soul — manually re-explain context | 3,000 ~ 10,000+ | | With Soul (L1) — keywords + TODO only | ~500 | | With Soul (L2) — + summary + decisions | ~2,000 | | With Soul (L3) — full context restore | ~4,000 |

Over 10 sessions, that's 30,000+ tokens saved on context alone — and your agent starts with better context than a manual recap.

How It Works

Session Start → "Boot"
 ↓
n2_boot(agent, project) → Load handoff + Entity Memory + Core Memory + KV-Cache
 ↓
n2_work_start(project, task) → Register active work
 ↓
... your agent works normally ...
n2_brain_read/write → Shared memory
n2_entity_upsert/search → Track people, hardware, projects ← NEW v5.0
n2_core_read/write → Agent-specific persistent facts ← NEW v5.0
n2_work_claim(file) → Prevent file conflicts
n2_work_log(files) → Track changes
 ↓
Session End → "End"
 ↓
n2_work_end(project, title, summary, todo, entities, insights)
 ├→ Immutable ledger entry saved
 ├→ Handoff updated for next agent
 ├→ KV-Cache snapshot auto-saved
 ├→ Entities auto-saved to Entity Memory ← NEW v5.0
 ├→ Insights archived to memory ← NEW v5.0
 └→ File ownership released

Features

| Feature | What it does | |---------|-------------| | Soul Board | Project state + TODO tracking + handoffs between agents | | Immutable Ledger | Every work session recorded as append-only log | | KV-Cache | Session snapshots with compression + tiered storage (Hot/Warm/Cold) | | Forgetting Curve GC | v8 — Ebbinghaus-based intelligent memory retention | | Async I/O | v8 — Non-blocking I/O on all hot-path operations | | Schema v2 | v8 — Access tracking + importance scoring + auto-migration | | Shared Brain | File-based shared memory with path traversal protection | | Entity Memory | Auto-tracks people, hardware, projects, concepts across sessions | | Core Memory | Agent-specific always-loaded facts (identity, rules, focus) | | Autonomous Extraction | Auto-saves entities and insights at session end | | Context Search | Keyword search across brain memory and ledger | | File Ownership | Prevents multi-agent file editing collisions | | Dual Backend | JSON (zero deps) or SQLite for performance | | Semantic Search | Optional Ollama embedding (nomic-embed-text) | | Backup/Restore | Incremental backups with configurable retention | | Cloud Storage | Store memory anywhere — Google Drive, NAS, network server, any path |

Cloud Storage — Store Your AI Memory Anywhere

One line of config. Zero API keys. Zero monthly fees.

Soul takes a radically different approach to cloud storage:

// config.local.js — This is ALL you need
module.exports = {
 DATA_DIR: 'G:/My Drive/n2-soul', // Google Drive
};

That's it. Your AI memory is now in the cloud. Every session, every handoff, every ledger entry — automatically synced by Google Drive. No OAuth, no API keys, no SDK.

How It Works

Soul stores everything as plain JSON files. Any folder that your OS can read = Soul's cloud. The cloud provider handles sync — Soul doesn't even know it's "in the cloud."

Supported Storage

| Storage | Example DATA_DIR | Cost | |---------|-------------------|:----:| | Local (default) | ./data | Free | | **Google Drive