内容
# SOLUM
**轻量级到可以在树莓派上运行，但功能足够强大，适用于整个智能代理栈。**
Solum 是一个自主托管的 AI 记忆服务器。它为任何与 MCP 兼容的 AI 提供持久的、可搜索的记忆，这些记忆存储在您自己的硬件上。您的思绪、您的机器、您的数据。（前身为 Strata。）
## 问题
您的 AI 在每次会话结束时都会忘记一切。每次新的聊天都从零开始。Solum 解决了这个问题：它为 Claude Code、Codex 或任何 MCP 客户端提供了一个长期记忆，这个记忆在会话和代理之间持续存在，因此上下文可以跨越人员、项目和对话之间的间隔。
## 在您自己的硬件上运行
Solum 可以在您已经拥有的任何设备上运行：台式机、迷你电脑、NAS、家庭实验室盒子、VPS 或树莓派。重点是它运行在您自己的机器上，而不是别人的云中。
它可以在树莓派上轻松运行的事实证明了这一点，而不是定义：它不需要昂贵的基础设施。语义搜索、嵌入、仪表盘、文件保险库，所有这些都可以安装在功耗极低的小主板上。当您需要时，相同的安装可以扩展到一台真正的服务器。
## 功能
- **按含义搜索。** 询问“与钱有关的事”，它会找到您关于预算和投资的笔记。不是关键词匹配，而是通过向量嵌入实现真正的语义理解。
- **混合搜索。** 在确切的术语很重要时，将关键词匹配和含义结合起来。
- **每个代理的记忆，带有权限。** 每个 AI 代理都有自己的密钥，拥有细粒度的读取、写入、删除和管理员权限。禁用密钥，代理立即被切断。
- **分支和星星。** 相关想法聚集在父星下作为分支，因此项目及其笔记可以作为一个集群读取，而不是分散的条目。中心位置的星星 0 是您，所有记忆都围绕它运转。
- **文件保险库。** 将真实文件附加到想法上：代码、文档、整个项目存档。想法是索引，保险库持有内容。
- **审计轨迹。** 每个创建、更新和删除操作都被记录，因此您可以查看谁或什么修改了记忆以及何时修改。
- **重复数据保护。** 尝试保存与您已经保存的内容相似的内容，Solum 会警告您，而不是累积重复数据。
- **所有者控制的删除。** AI 可以读取和写入，但如果您不授予它管理员密钥，它就无法删除记忆。您的数据，您控制。
## 记忆工作原理
普通的数据库通过关键词搜索。存储“转换职业”，搜索“新工作”时，您什么也找不到。
Solum 将每个想法转换为一个 768 维向量，捕捉其含义，因此“转换职业”、“新工作”和“职业变更”都能相互找到。默认情况下，这些向量存储在本地 SQLite 文件中，相似性在进程中运行，对于单个人来说已经足够。如果指向 PostgreSQL，相同的搜索通过 pgvector 在数据库中运行，具有 HNSW 索引，可同时处理多个代理。无论哪种方式，嵌入模型（BAAI/bge-base-en-v1.5）都通过 ONNX Runtime 在本地运行，使用大约 100 到 150 MB 的 RAM，闲置几分钟后卸载。
## 立即试用（无需设置）
想在设置任何内容之前看到 Solum 运行？下载此存储库并运行演示。它将示例记忆加载到一个临时本地数据库中，并在您的浏览器中打开仪表盘。无需 PostgreSQL，无需 Docker，无需帐户。您只需要 Python。
```bash
git clone https://github.com/agenerationforwordz-tech/solum.git
cd solum
python start_demo.py
```
在 Windows 上，您可以直接双击 `run-demo.bat`（在 Mac 或 Linux 上，则为 `./run-demo.sh`）。启动器会在第一次安装依赖项，然后在 `http://localhost:4320` 打开带有仪表盘、语义搜索和 3D 星图的浏览器，星图已经充满了示例想法。所有数据都存储在每次运行都会重置的临时数据库中，因此您可以随意探索。当您准备好创建自己的数据库时，请参见下面的“开始使用”。
## 开始使用
Solum 有两个数据库后端。**SQLite 是默认的，不需要额外的设置**，非常适合单个人或小型设置。**PostgreSQL** 适用于多代理、高并发使用。您可以通过一个环境变量来选择。
### 快速开始（SQLite，立即生效）
整个数据库是一个本地文件。无需外部服务。
```bash
git clone https://github.com/agenerationforwordz-tech/solum.git
cd solum
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r requirements.txt
python server.py
```
就这样。打开 `http://localhost:4320`，仪表盘将引导您完成首次运行设置。嵌入模型仅需下载一次（约 170 MB），之后会被缓存。您的记忆存储在 `data/brain.db` 中。
### 扩展（PostgreSQL + pgvector）
用于并发多代理访问和数据库内向量搜索。需要安装了 pgvector 扩展的 PostgreSQL。
**1. 创建数据库并加载模式：**
```bash
sudo -u postgres psql -c "CREATE USER solum WITH PASSWORD 'choose-a-db-password';"
sudo -u postgres psql -c "CREATE DATABASE solum_db OWNER solum;"
sudo -u postgres psql -d solum_db -c "CREATE EXTENSION IF NOT EXISTS vector;"
PGPASSWORD='choose-a-db-password' psql -h localhost -U solum -d solum_db -f solum_pg_schema.sql
```
**2. 将 Solum 指向它并运行：**
```bash
export SOLUM_DB_BACKEND=postgresql
export SOLUM_PG_HOST=localhost
export SOLUM_PG_DB=solum_db
export SOLUM_PG_USER=solum
export SOLUM_PG_PASSWORD='choose-a-db-password'
python server.py
```
## 首次运行设置
打开 `http://your-server:4320`，您将看到四个步骤：
1. **密码。** 创建您的所有者帐户（PBKDF2-SHA256，哈希，不存储为明文）。
2. **恢复短语。** 一个 12 个单词的短语，仅显示一次。写下来。这是重置忘记密码的唯一方法，它仅存储为哈希。
3. **管理员密钥。** 选择您自己的或生成一个，仅显示一次。这是您授予 AI 用于删除的凭证，也是命令行或自动化的密钥。您的正常仪表盘登录已经在浏览器中授予管理员权限，因此您仅需要此密钥用于非浏览器访问。
4. **星星 0。** 告诉 Solum 这个实例是谁的以及您用它做什么。这是您的星图的中心，它也可以被您的代理读取，以便它们知道它们正在处理谁的记忆。
## 连接 AI
每个 MCP 工具都需要一个启用的代理密钥，因此首先在 `/admin/agents` 仪表盘中创建一个（设置其读取、写入和删除权限）。然后将您的客户端指向 MCP 端点并发送密钥。
### Claude Code
```bash
claude mcp add --transport http solum http://your-server:4320/mcp \
--header "X-API-Key: your-agent-key"
```
### 任意 HTTP 客户端
```bash
# 保存一个想法
curl -X POST http://your-server:4320/api/capture \
-H "Content-Type: application/json" \
-H "X-API-Key: your-agent-key" \
-d '{"content": "Solum is running on my own hardware", "tags": ["setup"]}'
# 按含义搜索
curl -X POST http://your-server:4320/api/search \
-H "Content-Type: application/json" \
-H "X-API-Key: your-agent-key" \
-d '{"query": "server setup", "limit": 5}'
# 健康检查（无身份验证）
curl http://your-server:4320/health
```
## 配置
通过环境变量设置（可在 `config.py` 中找到完整列表）：
| 变量 | 默认值 | 功能 |
| --- | --- | --- |
| `SOLUM_DB_BACKEND` | `sqlite` | 设置为 `postgresql` 以使用 Postgres + pgvector |
| `SOLUM_PG_HOST` | `localhost` | PostgreSQL 主机 |
| `SOLUM_PG_DB` | `solum_db` | 数据库名称 |
| `SOLUM_PG_USER` | `solum` | 数据库用户 |
| `SOLUM_PG_PASSWORD` | *(空)* | 数据库密码（仅限环境变量，不应硬编码） |
| `SOLUM_PORT` | `4320` | 服务器端口 |
| `SOLUM_HOST` | `0.0.0.0` | 监听地址 |
| `SOLUM_DATA_DIR` | `./data` | 数据和保险库位置 |
| `SOLUM_ADMIN_KEY` | *(空)* | 可选的部署时间管理员密钥（您也可以在设置时设置一个） |
## MCP 工具
以下每个工具都需要一个启用的代理密钥，因此禁用的密钥会立即失去读取和写入访问权限。
| 工具 | 功能 |
| --- | --- |
| `capture_thought` | 保存记忆，自动标记，重复数据检查，可选分支父节点 |
| `semantic_search` | 按含义查找记忆 |
| `hybrid_search` | 关键词和含义混合搜索 |
| `get_relevant_context` | 智能包：重复数据删除，按类型分组 |
| `find_related` | 更多类似内容，针对特定想法 |
| `search_by_tag` / `search_by_person` | 按标签或人员过滤 |
| `search_advanced` | 堆栈过滤器：类型，标签，来源，机器，日期 |
| `temporal_search` | 在时间窗口内查找发生的事情 |
| `list_recent` | 最近捕获了什么 |
| `get_thought` / `get_children` | 读取一个想法，或星下的分支 |
| `update_thought` | 编辑想法（自动重新嵌入） |
| `delete_thought` | 删除想法（需要管理员密钥） |
| `set_parent` | 将想法链接为父星下的分支 |
| `get_stats` / `generate_report` | 数据库统计数据和趋势报告 |
| `startup_bundle` | 代理启动时的单一调用上下文 |
| `get_history` | 变更审计轨迹 |
## Web 仪表盘
Solum 配备了完整的仪表盘，位于 `/dashboard`，和 3D 星图，位于 `/constellation`。
- **捕获和编辑** 带有标签、人员和十种想法类型的想法。
- **语义和标签搜索** 直接从浏览器进行。
- **星图：** 每个记忆都是一个星星，按类型着色，按含义聚类，星图中心为星星 0（您）。
- **代理管理器**，位于 `/admin/agents`：创建代理密钥，设置权限，并翻转终止开关。您的仪表盘登录权限打开，无需单独的密钥。
- **帐户安全：** 密码更改、12 个单词的恢复短语、每个设备的会话和登录历史。
## 安全
- **每个代理的密钥**，具有细粒度的读取、写入、删除和管理员权限。每个 MCP 工具和 REST 端点都会检查它们。
- **仪表盘身份验证** 是独立的：PBKDF2-SHA256 密码哈希（480K 迭代，随机盐，恒定时间比较），256 位会话令牌和哈希的 12 个单词恢复短语。
- **所有者仅限删除。** AI 客户端在没有管理员密钥的情况下无法删除。
- **每个代理的终止开关。** 禁用任何代理密钥及其读取和写入访问权限立即停止。
- **全局紧急终止开关。** 一个切换按钮可以关闭整个实例的所有代理：所有 `/mcp` 和 `/api/*` 请求返回 503，没有代理可以触及内存。您的登录和管理员面板仍然可访问，以便您重新启用它，代理密钥无法撤销它，状态在重启后仍然存在。在 `/admin/agents` 的代理管理器中翻转它。
- **输入限制和强化：** 每个想法的大小限制和每个文件的大小限制，AI 内容的提示注入标记，输出转义，原子文件写入和保险库的路径遍历保护。
- **速率限制** 公共 REST API：每分钟 30 个请求，每个 IP。
## 构建方式
```
AI 客户端（Claude Code、Codex、机器人） 人类（浏览器）
| | |
MCP (/mcp) REST (/api/*) 仪表盘 + 星图
| | |
+----- server.py: 身份验证、速率限制、净化 -----+
| | |
代理密钥 代理密钥 密码 + 会话
| | |
embedder.py vault.py auth.py（PBKDF2、种子）
ONNX 模型 文件存储 |
| | |
+--- db.py: 默认 SQLite，或 PostgreSQL + pgvector --+
想法、嵌入、保险库、用户、会话
```
## 许可证
PolyForm 非商业许可 1.0.0。版权所有 (c) 2026 A Generation Forwordz 基金会。
源代码可用。 使用它，运行它，研究它，改进它，分享它。 保持非商业化并保持署名。 有关完整条款，请参见 [LICENSE](LICENSE)。
由 Christian Mitchell 构建。 如果您运行它，请保持署名。
