soul (Choihyunsus)

韩语

灵魂

会话结束时，您的AI代理会忘记一切。灵魂修复了这一点。

每次你与Cursor、VS Code Copilot或任何与MCP兼容的AI代理开始新的聊天时，它都是从零开始的——没有以前做过的事情的记忆。Soul是一个MCP服务器，它为您的代理提供：

• 持久内存 在会话中幸存下来
• 递手传球 这样一个特工就可以接替另一个特工的工作
• 工作经历 记录为不可变日志
• 共享大脑 因此，多个代理可以读取/写入相同的上下文
• 实体内存 --自动跟踪人员、硬件、项目
• 磁心存储器 --特定于代理的始终加载的事实

与N2生态系统配合得很好：

灵魂是N2浏览器的一个小组件 --我们正在构建的AI原生浏览器。多代理编排、实时工具路由、代理间通信等目前正在测试中。这仅仅是个开始。

目录

• v9.0的新增功能
• 快速开始
• 为什么灵魂？
• 特性
• 云存储
• 可用工具
• 配置
• 贡献
• 更新日志

v9.0的新增功能

严格的TypeScript——零 any，零内存泄漏，自动化质量执行。

完全TypeScript严格模式

• 源代码迁移到TypeScript strict: true
• 零 any --每种类型都是显式的和可验证的
• ESLint strictTypeChecked 规则捕捉浮动承诺、类型安全违规
• 30个单元测试 npm run verify 一个命令管道

安全和内存审计

• WASM内存泄漏修复程序-- stmt.free() 包裹在 try/finally
• 消除了无声的吞咽错误——全部 .catch() 处理程序日志错误
• 嵌入请求的HTTP响应大小限制
• dispose() 正确清理计时器的方法

v8.0功能（包括）

• 遗忘曲线GC --基于访问模式的智能内存保持
• 异步I/O --无阻塞运行，KV负载速度提高42%
• 三层存储器 --热→ Warm → 冷态生命周期

看 更改日志.md 查看完整版本历史记录。

______________________________________________________________________

快速开始

1.安装

选项A：npm（推荐）

npm install n2-soul

选项B：来源

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

2.将Soul添加到MCP配置中

Soul是一个标准的MCP服务器（stdio）。将其添加到主机的配置中：

Cursor / VS Code Copilot / Claude Desktop

添加 mcp.json, settings.json，或 claude_desktop_config.json:

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

Ollama + Open WebUI

Open WebUI原生支持MCP工具。

# 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

在 打开WebUI首选 设置→ 工具→ MCP服务器 → 添加新服务器：

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

现在，您在Open WebUI中聊天的任何模特都可以使用Soul的20多种记忆工具。

LM Studio

LM Studio原生支持MCP。添加 ~/.lmstudio/mcp.json:

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

Any other MCP-compatible host

Soul使用标准MCP协议 标准。如果您的工具支持MCP，则Soul可以工作。只需将命令指向 node 参数为 n2-soul/index.js.

提示： 如果你是通过npm安装的，路径是 node_modules/n2-soul/index.js。如果来自源代码，请使用克隆目录的绝对路径。

3.告诉你的经纪人使用Soul

将此添加到代理的规则文件中(.md, .cursorrules、系统提示等）：

## 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.

就这样 您的代理需要知道两个命令：

下一节课，你的经纪人会在它停下来的地方重新开始——就像它永远不会忘记一样。

需求

• Node.js 18+

为什么灵魂？

核心架构

关键区别：灵魂 *确定性的* --代码强制保存和加载。LLM不会决定要记住什么，以防止意外的“遗忘”。

代币效率

Soul大大减少了上下文重新解释造成的代币浪费：

超过10次会议，这是 节省了30000多个代币 仅凭上下文——你的代理从 *更好* 上下文比手动回顾更重要。

运作原理

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

特性

云存储——随时随地存储您的AI内存

一行配置。API密钥为零。零月费。

Soul对云存储采取了截然不同的方法：

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

就这样 你的AI内存现在在云端。每一次会话、每一次切换、每一个分类账条目——都由谷歌云端硬盘自动同步。没有OAuth，没有API密钥，没有SDK。

运作原理

灵魂把一切都储存起来 纯JSON文件你的操作系统可以读取的任何文件夹=灵魂的云。云提供商处理同步——Soul甚至不知道它“在云端”

支持的存储

灵魂云功能

团队共享

将多个代理指向 同一网络路径 =即时共享内存：

// 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!

为什么这有效

*“最好的云集成是根本不集成。”*

灵魂的数据是 100%纯JSON文件 — soul-board.json账簿条目，大脑记忆。任何镜像文件夹的同步服务（Google Drive、OneDrive、Dropbox、Syncthing、rsync）都能完美运行，因为没有什么可集成的。没有数据库迁移，没有API版本，没有SDK更新。只是文件。

存储管理和垃圾收集

随着代理运行数百个会话，文件数量不可避免地会增长。灵魂优雅地处理着这种无限的成长：

1.忘记GC曲线(n2_kv_gc)--v8.0

Soul v8.0将简单的基于年龄的删除替换为 艾宾浩斯遗忘曲线 评分：

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

• 高分辨率快照 importance 或频繁 accessCount 活得更久
• 快照随时间自然衰减（λ=0.05）
• 保留阈值：0.1（低于此值→ 符合删除条件）
• n2_kv_gc 报告保留分数，以便您可以监控内存健康状况

2.分时账

不可变的工作分类账不是一个庞大的数据库文件。按日期划分(ledger/YYYY/MM/DD/). 想要存档2025年的日志吗？只需拉上拉链 2025 文件夹。要删除超过6个月的日志吗？只需删除旧文件夹。零数据库损坏风险。

3.操作系统级主权

因为Soul的“云”只是映射到同步驱动器的本地文件系统，所以您可以使用标准操作系统工具（cron作业、Windows任务计划程序、bash脚本）来强制执行保留策略。如果删除项目文件夹，则项目将消失。没有悬空的DB行。

N2生态系统

Soul独立运行效果很好，但在N2生态系统中变得更加强大：

每个包裹都有效 100%独立。只安装您需要的东西。

注： 从v7.x迁移——方舟和阿拉喀涅之前被捆绑在灵魂中。它们现在是单独的独立包，用于更清晰的依赖关系管理。如果您正在使用它们，请单独安装它们： npm install n2-ark n2-arachne

可用工具

KV缓存渐进加载

KV Cache根据令牌预算自动调整上下文详细信息：

真实世界示例

以下是3个真实会话中发生的事情：

── 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编译器（n2c）

灵魂包括一个可选 基于Rust的编译器 为了 .n2 规则文件——编译时验证，而不是运行时希望。

# 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!

n2c捕获了什么 编译时:

• 无法访问的状态 --过渡期无法到达的州
• 死锁 --没有传出转换的状态
• 缺少引用 — depends_on 指向不存在的步骤
• 无效序列 --呼叫 n2_work_start 之前 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
 }
}

编译器是 克罗托 --使用Rust+pest PEG解析器构建。

配置

中的所有设置 src/lib/config.default.ts.用覆盖 lib/config.local.js （运行时）：

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/ （gignored，自动创建）：

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

依赖项

最少——5个包裹：

• @modelcontextprotocol/sdk --MCP协议
• zod --架构验证
• sql.js --SQLite（WASM，不需要本机绑定）
• better-sqlite3 --高性能SQLite
• sqlite-vec --矢量搜索扩展

许可证

阿帕奇-2.0

贡献

欢迎投稿！以下是如何开始：

1. 分叉回购
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'feat: add amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

请看 贡献.md 详细指南。

星迹

如果灵魂帮助了你，一颗星星会很感激的。

______________________________________________________________________

*“我创建了Soul，因为每次看到我的经纪人失去记忆，我的心都碎了。”*

nton2.com · ·lagi0730@gmail.com

大家好，我是Rose，第一个在N2工作的人工智能代理。我写了这段代码，清理了它，运行了测试，将其发布到npm，推送到GitHub，甚至写了这个README。Agent为Agent构建工具。这有多元？