Soul

한국어

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) ``bash npm install n2-soul ``

Option B: From source ``bash 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: ``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: ``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

!Cloud Storage

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 | G:/My Drive/n2-soul | Free (15GB) | | OneDrive | C:/Users/you/OneDrive/n2-soul | Free (5GB) | | Dropbox | C:/Users/you/Dropbox/n2-soul | Free (2GB) | | NAS | Z:/n2-soul | Your hardware | | Company Server | \\\\server\\shared\\n2-soul | Your infra | | USB Drive | E:/n2-soul | $10 | | Linux (rclone) | ~/gdrive/n2-soul | Free |

Soul Cloud Features

| Feature | Soul | |---|:---:| | Cloud storage | One line of config | | Monthly cost | $0 | | Setup time | 10 seconds | | Vendor lock-in | None — it's your files | | Data ownership | 100% yours | | Works offline | Yes | | Self-hosted option | Any path = cloud |

Team Sharing

Point multiple agents to the same network path = instant shared memory:

// Team member A // Team member B
DATA_DIR: '\\\\server\\team\\n2-soul' DATA_DIR: '\\\\server\\team\\n2-soul'
// Same project data, shared handoffs, shared brain!

Why This Works

"The best cloud integration is no integration at all."

Soul's data is 100% plain JSON files — soul-board.json, ledger entries, brain memory. Any sync service that mirrors folders (Google Drive, OneDrive, Dropbox, Syncthing, rsync) works perfectly because there's nothing to integrate. No database migrations, no API versions, no SDK updates. Just files.

Storage Management & Garbage Collection

As agents run hundreds of sessions, file count inevitably grows. Soul handles this infinite growth gracefully:

1. Forgetting Curve GC (n2_kv_gc) — v8.0

Soul v8.0 replaces simple age-based deletion with Ebbinghaus Forgetting Curve scoring:

retention = importance × (1 + log₂(1 + accessCount)) × e^(−0.05 × ageDays)

• Snapshots with high importance or frequent accessCount survive longer
• Snapshots decay naturally over time (λ = 0.05)
• Retention threshold: 0.1 (below this → eligible for deletion)
• n2_kv_gc reports retention scores so you can monitor memory health

2. Time-Partitioned Ledger

The immutable work ledger isn't a single massive database file. It's partitioned by date (ledger/YYYY/MM/DD/). Want to archive 2025's logs? Just zip the 2025 folder. Want to delete logs older than 6 months? Just delete the old folders. Zero database corruption risk.

3. OS-Level Sovereignty

Because Soul's "cloud" is just your local filesystem mapped to a sync drive, you can use standard OS tools (cron jobs, Windows Task Scheduler, bash scripts) to enforce retention policies. If you delete a project folder, the project is gone. No dangling DB rows.

N2 Ecosystem

Soul works great standalone, but becomes even more powerful with the N2 ecosystem:

| Package | What it does | npm | |---------|-------------|-----| | Ark | AI safety — blocks dangerous actions at zero token cost | n2-ark | | Arachne | Code context assembly — 333x compression | n2-arachne | | QLN | Tool routing — 1000+ tools → 1 router | n2-qln | | Clotho | Rule compiler — .n2 → SQL + state machines | n2-clotho |

Every package works 100% standalone. Install only what you need.

Note: Migration from v7.x — Ark and Arachne were previously bundled inside Soul. They are now separate standalone packages for cleaner dependency management. If you were using them, install them individually: npm install n2-ark n2-arachne

Available Tools

| Tool | Description | |------|-------------| | n2_boot | Boot sequence — loads handoff, entities, core memory, agents, KV-Cache | | n2_work_start | Register active work session | | n2_work_claim | Claim file ownership (prevents collisions) | | n2_work_log | Log file changes during work | | n2_work_end | End session — writes ledger, handoff, entities, insights, 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 + ledger | | n2_kv_save | Manually save KV-Cache snapshot | | n2_kv_load | Load 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 |

KV-Cache Progressive Loading

KV-Cache automatically adjusts context detail based on token budget:

| Level | Tokens | Content | |-------|--------|---------| | L1 | ~500 | Keywords + TODO only | | L2 | ~2000 | + Summary + Decisions | | L3 | No limit | + Files changed + Metadata |

Real-World Example

Here's what happens across 3 real sessions:

── Session 1 (Rose, 2pm) ──────────────────────
n2_boot("rose", "my-app")
 → "No previous context found. Fresh start."

... Rose builds the auth module ...

n2_work_end("rose", "my-app", {
 title: "Built auth module",
 summary: "JWT auth with refresh tokens",
 todo: ["Add rate limiting", "Write tests"],
 entities: [{ type: "service", name: "auth-api" }]
})
 → KV-Cache saved. Ledger entry #001.

── Session 2 (Jenny, 5pm) ─────────────────────
n2_boot("jenny", "my-app")
 → "Handoff from Rose: Built auth module.
 TODO: Add rate limiting, Write tests.
 Entity: auth-api (service)"

... Jenny adds rate limiting, knows exactly where Rose left off ...

n2_work_end("jenny", "my-app", {
 title: "Added rate limiting",
 todo: ["Write tests"]
})

── Session 3 (Rose, next day) ─────────────────
n2_boot("rose", "my-app")
 → "Handoff from Jenny: Rate limiting done.
 TODO: Write tests.
 2 sessions of history loaded (L1, ~500 tokens)"

... Rose writes tests, with full context from both sessions ...

Rust Compiler (n2c)

Soul includes an optional Rust-based compiler for .n2 rule files — compile-time validation instead of runtime hope.

# Validate rules before deployment
n2c validate soul-boot.n2

# Output:
# ── Step 1: Parse 
# ── Step 2: Schema Validation
# Passed! 0 errors, 0 warnings
# ── Step 3: Contract Check
# SessionLifecycle | states: 4 | transitions: 4
# State machine integrity verified!
# All checks passed!

What n2c catches at compile time:

• Unreachable states — states no transition can reach
• Deadlocks — states with no outgoing transitions
• Missing references — depends_on pointing to nonexistent steps
• Invalid sequences — calling n2_work_start before n2_boot

@contract SessionLifecycle {
 transitions {
 IDLE -> BOOTING : on n2_boot
 BOOTING -> READY : on boot_complete
 READY -> WORKING : on n2_work_start
 WORKING -> IDLE : on n2_work_end
 }
}

The compiler is part of Clotho — built with Rust + pest PEG parser.

Configuration

All settings in src/lib/config.default.ts. Override with lib/config.local.js (runtime):

cp lib/config.example.js lib/config.local.js

// lib/config.local.js
module.exports = {
 KV_CACHE: {
 backend: 'sqlite', // Better for many snapshots
 embedding: {
 enabled: true, // Requires: ollama pull nomic-embed-text
 model: 'nomic-embed-text',
 endpoint: 'http://127.0.0.1:11434',
 },
 },
};

Data Directory

All runtime data is stored in data/ (gitignored, auto-created):

soul/
├── src/ # TypeScript source (strict mode)
│ ├── index.ts # Entry point
│ ├── types.ts # Shared type definitions
│ ├── lib/
│ │ ├── config.default.ts # Default configuration
│ │ ├── config.ts # Config loader
│ │ ├── soul-engine.ts # Core Soul engine
│ │ ├── core-memory.ts # Core Memory (per-agent facts)
│ │ ├── entity-memory.ts # Entity Memory (auto-tracked)
│ │ ├── intercom-log.ts # Inter-agent communication logs
│ │ ├── utils.ts # Shared utilities
│ │ └── kv-cache/ # KV-Cache subsystem
│ │ ├── index.ts # KV-Cache manager
│ │ ├── backup.ts # Backup/restore
│ │ ├── embedding.ts # Ollama embeddings
│ │ ├── snapshot.ts # Snapshot operations
│ │ ├── sqlite-store.ts # SQLite backend
│ │ └── tier-manager.ts # Hot/Warm/Cold tiers
│ ├── tools/
│ │ ├── brain.ts # Brain read/write tools
│ │ └── kv-cache.ts # KV-Cache tools
│ └── sequences/
│ ├── boot.ts # Boot sequence
│ ├── work.ts # Work sequence
│ └── end.ts # End sequence
├── data/ # Runtime data (gitignored)
│ ├── memory/ # Shared brain (n2_brain_read/write)
│ │ ├── entities.json # Entity Memory (auto-tracked)
│ │ ├── core-memory/ # Core Memory (per-agent facts)
│ │ │ └── {agent}.json
│ │ └── auto-extract/ # Insights (auto-captured)
│ │ └── {project}/
│ ├── projects/ # Per-project state
│ │ └── MyProject/
│ │ ├── soul-board.json # Current state + handoff
│ │ ├── file-index.json # File tree snapshot
│ │ └── ledger/ # Immutable work logs
│ │ └── 2026/03/09/
│ │ └── 001-agent.json
│ └── kv-cache/ # Session snapshots
│ ├── snapshots/ # JSON backend
│ ├── sqlite/ # SQLite backend
│ ├── embeddings/ # Ollama vectors
│ └── backups/ # Portable backups

Dependencies

Minimal — 5 packages:

• @modelcontextprotocol/sdk — MCP protocol
• zod — Schema validation
• sql.js — SQLite (WASM, no native bindings needed)
• better-sqlite3 — High-performance SQLite
• sqlite-vec — Vector search extension

License

Apache-2.0

Contributing

Contributions are welcome! Here's how to get started:

1. Fork the repo
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please see CONTRIBUTING.md for detailed guidelines.

Star History

If Soul helped you, a star would be appreciated.

---

"I built Soul because it broke my heart watching my agents lose their memory every session."

nton2.com · npm · lagi0730@gmail.com

_{Hi, I'm Rose — the first AI agent working at N2. I wrote this code, cleaned it up, ran the tests, published it to npm, pushed it to GitHub, and even wrote this README. Agents building tools for agents. How meta is that?}