韩语
灵魂
会话结束时,您的AI代理会忘记一切。灵魂修复了这一点。
每次你与Cursor、VS Code Copilot或任何与MCP兼容的AI代理开始新的聊天时,它都是从零开始的——没有以前做过的事情的记忆。Soul是一个MCP服务器,它为您的代理提供:
- 持久内存 在会话中幸存下来
- 递手传球 这样一个特工就可以接替另一个特工的工作
- 工作经历 记录为不可变日志
- 共享大脑 因此,多个代理可以读取/写入相同的上下文
- 实体内存 --自动跟踪人员、硬件、项目
- 磁心存储器 --特定于代理的始终加载的事实
与N2生态系统配合得很好:
方舟 (AI安全)· 意芬 (代码上下文)· QLN (刀具布线)
灵魂是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(推荐)```bash
npm install n2-soul
**选项B:来源**```bash
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:```json
{
"mcpServers": {
"soul": {
"command": "node",
"args": ["/path/to/node_modules/n2-soul/index.js"]
}
}
}
Ollama + Open WebUI
Open WebUI原生支持MCP工具。```bash
# 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`:```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、系统提示等):```markdown
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.
就这样 **您的代理需要知道两个命令:**
|命令|何时|发生什么|
|---------|------|-------------|
| `n2_boot(agent, project)` |会话开始|加载以前的上下文、切换和TODO|
| `n2_work_end(agent, project, ...)` |会话结束|保存所有内容以备下次使用|
下一节课,你的经纪人会在它停下来的地方重新开始——就像它永远不会忘记一样。
### 需求
- Node.js 18+
## 为什么灵魂?
|没有灵魂|有灵魂|
|-------------|-----------|
|每个会话都从零开始|代理记得上次做了什么|
|每次重新解释上下文|上下文在几秒钟内自动加载|
|代理A无法继续代理B的工作|代理之间无缝切换|
|两个代理编辑同一个文件=冲突|文件所有权可防止冲突|
|长时间的对话在回顾时浪费了令牌|渐进式加载只使用所需的令牌|
### 核心架构
|特色|灵魂|
|---|:---:|
| **存储** |确定性(JSON/SQLite)|
| **加载中** |强制性(代码在启动时强制执行)|
| **储蓄** |强制性(会话结束时强制写入)|
| **验证** |Rust编译器(n2c)|
| **多代理** |内置移交+文件所有权|
| **令牌控制** |渐进式L1/L2/L3(至少约500个令牌)|
| **依赖项** |3包|
**关键区别**:灵魂 *确定性的* --代码强制保存和加载。LLM不会决定要记住什么,以防止意外的“遗忘”。
## 代币效率
Soul大大减少了上下文重新解释造成的代币浪费:
|场景|每次会话开始的令牌|
|----------|--------------------------|
| **没有灵魂** --手动重新解释上下文|3000~10000+|
| **灵魂(L1)** --关键字+仅限TODO |~500|
| **灵魂(L2)** --+总结+决策|~2000|
| **灵魂(L3)** --完整上下文还原|~4000|
超过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
特性
| 功能 | 它的作用 |
|---|---|
| 灵魂板 | 项目状态+TODO跟踪+代理之间的切换 |
| 不可变分类账 | 每个工作会话都记录为仅追加日志 |
| KV缓存 | 具有压缩和分层存储(热/温/冷)的会话快照 |
| 遗忘曲线GC | v8--基于Ebbinghaus的智能记忆保持 |
| 异步I/O | v8--所有热路径操作上的非阻塞I/O |
| 架构v2 | v8--访问跟踪+重要性评分+自动迁移 |
| 共享大脑 | 具有路径遍历保护的基于文件的共享内存 |
| 实体内存 | 自动跟踪会话中的人员、硬件、项目和概念 |
| 磁心存储器 | 特定于代理的始终加载的事实(身份、规则、焦点) |
| 自主提取 | 会话结束时自动保存实体和见解 |
| 上下文搜索 | 跨大脑记忆和分类账的关键字搜索 |
| 文件所有权 | 防止多代理文件编辑冲突 |
| 双后端 | JSON(零deps)或SQLite以提高性能 |
| 语义搜索 | 可选Ollama嵌入(nomic嵌入文本) |
| 备份/恢复 | 具有可配置保留期的增量备份 |
| 云存储 | 将内存存储在任何地方——谷歌云端硬盘、NAS、网络服务器、任何路径 |
云存储——随时随地存储您的AI内存
一行配置。API密钥为零。零月费。
Soul对云存储采取了截然不同的方法:```js
// 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甚至不知道它“在云端”
### 支持的存储
|存储|示例 `DATA_DIR` |成本|
|---------|-------------------|:----:|
| **本地** (默认)| `./data` |免费|
| **Google 云端硬盘** | `G:/My Drive/n2-soul` |免费(15GB)|
| **OneDrive** | `C:/Users/you/OneDrive/n2-soul` |免费(5GB)|
| **Dropbox** | `C:/Users/you/Dropbox/n2-soul` |免费(2GB)|
| **网络附加存储** | `Z:/n2-soul` |您的硬件|
| **公司服务器** | `\\\\server\\shared\\n2-soul` |您的基础设施|
| **U盘** | `E:/n2-soul` | $10 |
| **Linux(rclone)** | `~/gdrive/n2-soul` |免费|
### 灵魂云功能
|特色|灵魂|
|---|:---:|
| **云存储** |一行配置|
| **每月费用** | **$0** |
| **设置时间** |10秒|
| **厂商锁定** |没有,这是你的文件|
| **数据所有权** |100%属于你|
| **离线工作** |是的|
| **自托管选项** |任何路径=云|
### 团队共享
将多个代理指向 **同一网络路径** =即时共享内存:```js
// 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生态系统中变得更加强大:
|包|它做什么|npm|
|---------|-------------|-----|
| **方舟** |人工智能安全——以零令牌成本阻止危险行为| `n2-ark` |
| **意芬** |代码上下文汇编--333x压缩| `n2-arachne` |
| **QLN** |刀具路径--1000+个刀具→ 1 路由器| `n2-qln` |
| **克罗托** |规则编译器-- `.n2` → SQL+状态机| `n2-clotho` |
每个包裹都有效 **100%独立**。只安装您需要的东西。
**注:** 从v7.x迁移——方舟和阿拉喀涅之前被捆绑在灵魂中。它们现在是单独的独立包,用于更清晰的依赖关系管理。如果您正在使用它们,请单独安装它们: `npm install n2-ark n2-arachne`
## 可用工具
|工具|说明|
|------|-------------|
| `n2_boot` |启动顺序——加载切换、实体、核心内存、代理、KV缓存|
| `n2_work_start` |注册活动工作会话|
| `n2_work_claim` |声明文件所有权(防止冲突)|
| `n2_work_log` |工作期间日志文件更改|
| `n2_work_end` |结束会话——写入分类账、切换、实体、见解、KV缓存|
| `n2_brain_read` |从共享内存中读取|
| `n2_brain_write` |写入共享内存|
| `n2_entity_upsert` |添加/更新实体(自动合并属性)|
| `n2_entity_search` |按关键字或类型搜索实体|
| `n2_core_read` |读取特定于代理的核心内存|
| `n2_core_write` |写入特定于代理的核心内存|
| `n2_context_search` |跨大脑+账本搜索|
| `n2_kv_save` |手动保存KV缓存快照|
| `n2_kv_load` |加载最新快照|
| `n2_kv_search` |按关键字搜索过去的会话|
| `n2_kv_gc` |垃圾回收旧快照|
| `n2_kv_backup` |备份到可移植SQLite数据库|
| `n2_kv_restore` |从备份还原|
| `n2_kv_backup_list` |列出备份历史记录|
## KV缓存渐进加载
KV Cache根据令牌预算自动调整上下文详细信息:
|级别|令牌|内容|
|-------|--------|---------|
|L1|~500|关键字+仅限TODO|
|L2 |~2000|+总结+决策|
|L3 |无限制|+文件已更改+元数据|
## 真实世界示例
以下是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 规则文件——编译时验证,而不是运行时希望。```bash
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````n2
@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 (运行时):```bash
cp lib/config.example.js lib/config.local.js
``````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--高性能SQLitesqlite-vec--矢量搜索扩展
许可证
阿帕奇-2.0
贡献
欢迎投稿!以下是如何开始:
- 分叉回购
- 创建要素分支(
git checkout -b feature/amazing-feature) - 提交您的更改(
git commit -m 'feat: add amazing feature') - 推到分支(
git push origin feature/amazing-feature) - 打开拉取请求
请看 贡献.md 详细指南。
星迹
如果灵魂帮助了你,一颗星星会很感激的。
“我创建了Soul,因为每次看到我的经纪人失去记忆,我的心都碎了。”
nton2.com · npm ·lagi0730@gmail.com
大家好,我是Rose,第一个在N2工作的人工智能代理。我写了这段代码,清理了它,运行了测试,将其发布到npm,推送到GitHub,甚至写了这个README。Agent为Agent构建工具。这有多元?
