Strata

STRATA v2.2

此仓库已由 SOLUM 取代。 SOLUM 是本项目的活跃开发版本：改用 PostgreSQL + pgvector，而非 SQLite，提供更多工具，并修复了此处尚未修复的多个问题。新用户应从 SOLUM 开始。 此仓库仍可供参考。

可自托管的 AI 记忆服务。你的想法、你的硬件、你的数据。

为什么选择 Strata？

会话一结束，你的 AI 就会忘记一切。Strata 可以解决这个问题。它为任何兼容 MCP 的 AI 提供持久记忆，并将记忆存储在你的硬件上——不在云端，也不在别人的服务器上。按含义搜索、附加真实文件，并在 Raspberry Pi 上运行所有功能。

v2.2 新增内容

v2.0 让 Strata 知道是谁在交互。v2.2 则让它能够扩展、审计并记住过去。

• 每个 Agent 独立的 API 密钥——每个 AI Agent 都有自己的密钥，并可设置细粒度的 read / write / delete / admin / kill 权限。你不必再让所有工具共用一个密钥。可从 /admin/agents 管理密钥。
• 全局 MCP 紧急开关——只需切换一次，即可阻止所有 Agent 使用 MCP、REST 和 /api/*。任何具有写入或 kill 权限的 Agent 都可以拉下刹车；只有人工管理员可以重新启用。专为工具失控时的紧急情况打造。
• 3D 星座视图——在 /constellation 实时观察你的大脑如何思考。采用神圣几何布局（生命之花背景、十二面体簇、斐波那契球面分布），并提供每个 Agent 的专属颜色、实时活动流，以及在 MCP 离线时让整个场景降低饱和度的紧急开关指示器。
• 每个 Agent 独有的身份颜色——每个 Agent 都会从精选调色板中获得一种颜色，可在管理面板中编辑。颜色会显示在星座视图中，让你一眼就能看出哪个 Agent 在做什么。
• 静态数据加密（可选）——使用 SQLCipher AES-256 加密，密钥存放在仅 root 可访问的文件中。默认不启用；在威胁模型需要时，只需设置一个环境变量并运行安装脚本即可启用。
• 文件级强化（可选）——专用的 strata 系统用户拥有数据库，权限模式设为 600。SSH 用户将无法再通过直接编辑 SQLite 文件来绕过 API。
• 演示模式——设置 STRATA_DEMO_MODE=true 即可运行公开演示，控制面板接受空密码（登录界面仍会显示，让访客了解此功能已提供身份验证）。

v2.2 新增：

• PostgreSQL + pgvector 后端 — SQLite 仍是快速演示的默认选项，但生产环境请设置 STRATA_DB_BACKEND=postgresql。PostgreSQL 原生支持多个 Agent 并发写入（不再需要写入队列），pgvector 则使用 HNSW 索引在数据库中进行相似度搜索。可扩展至 100 万条以上的想法。
• CSV 审计日志 — 每个 Agent 的操作都会记录到 data/audit/ 中按日生成的 CSV 文件。完整的回放记录：谁搜索了什么、返回了哪些想法、耗时多久。这是透明度层，可精确追踪 AI 如何构建对你数据的理解。通过 GET /api/audit 查看。
• Strata 安装前的历史记录（负 ID） — 使用 capture_legacy 导入你在安装 Strata 之前的记忆。这些记忆会获得负 ID（-1、-2、-3……），并与当前想法一起存放在同一个星群中。AI 记忆并非从安装之日才开始——你想追溯多久都可以。在星群查看器中点击“THOUGHTS”，即可切换当前视图和历史视图。
• 10 种想法类型 — 从 8 种扩展为 10 种，并附有清晰说明，帮助 AI Agent 学会何时使用每种类型。新增了 idea（头脑风暴，尚未决定）和 observation（观察到的模式，尚未得出结论）。Agent 协议现在明确说明了类型选择规则，让每位新用户的星群都能保持均衡。
• 更新后的 Agent 协议 — strata_status 现在会向 Agent 介绍全部 10 种类型、负 ID 历史记录、审计日志和结果循环追踪。无需 CLAUDE.md——协议本身就是入门指南。
• 星群相机修复 — 点击一颗星时，相机将飞过它并回望，使原点星继续显示在背景中，作为参照点。
• 演示模式改进 — 在演示模式下，无需管理员密钥也可创建 Agent 和使用 MCP 紧急开关。

此外还有你已熟悉的 v1 功能：语义搜索、文件保险库、重复内容防护、密码 + 助记词控制面板身份验证、深色主题，可在 Pi 上运行。

我开发它，是因为我受够了 AI 工具在会话之间忘掉一切。STRATA 为任何兼容 MCP 的 AI（Claude Code、Codex CLI，以及未来的其他工具）提供一个持久化大脑，运行在你自己的机器上。不在云端。不在别人的服务器上。就在你这里。

它可以运行在 Raspberry Pi 4B 上。没错，整个系统——语义搜索、文件存储、嵌入——都能在一台配备 4GB RAM、售价 55 美元的电脑上运行。

它能做什么

• 按含义搜索 — 搜索“钱相关的东西”，就能找到关于 Bitcoin、投资和预算的笔记。不是关键词匹配，而是真正理解含义。
• 文件保险库 — 为想法附加实际文件，包括代码、文档和项目存档。想法是索引，保险库存放实际文件。
• 自动标记 — 写到 Docker？它会自动添加标签。提到 URL？也会添加标签。无需手动整理。
• 重复内容防护 — 如果你试图保存已保存过的内容，它会发现并发出警告。
• 访问追踪 — 查看哪些记忆确实会被使用，哪些只是闲置在那里。
• 仅管理员可删除 — AI 可以读取和写入记忆，但没有你的明确管理员密钥，绝不能删除任何内容。你的数据，由你掌控。

我为什么这样构建

普通数据库按关键词搜索。如果你保存了“转换职业”，却搜索“找新工作”，就什么也找不到。

STRATA 会将每个想法转换成一个 768 维向量，以表示它的含义。相似的想法会在向量空间中彼此靠近。因此，“转换职业”“找新工作”和“职业转变”都能互相找到。

模型通过 ONNX Runtime 在本地运行（而不是 PyTorch——在 ARM 上仅导入它就会占用 1.5GB）。嵌入模型总共占用约 100–150MB RAM，并会在空闲 5 分钟后卸载。

文件库

这让 STRATA 不只是一个笔记应用。

你记录一个与项目有关的想法，然后将实际源文件附加到其中。之后，当你或你的 AI 搜索该主题时，会同时看到这个想法和附加到它的所有文件列表。AI 会挑选所需的文件，只提取这些文件，而不会将整个硬盘中的内容都载入内存。

文件在磁盘上的组织方式如下：

data/vault/
  my-laptop/
    2026-03/
      42/
        server.py
        config.py
  my-desktop/
    2026-03/
      55/
        training_data.csv

按设备和月份整理。如果愿意，你也可以手动浏览。文件最大可达 1GB；返回给 AI 的文本文件上限为 5MB（避免撑爆上下文窗口）。

Strata 之前的历史记录（负 ID）

你的 AI 记忆不必从安装当天才开始。导入你的过往记录：

# Via MCP tool
capture_legacy(
    content="Decided to self-host everything after the cloud bill hit $400/mo",
    thought_type="decision",
    tags=["infrastructure", "self-hosting"],
    original_date="2024-06-15",
    source="pre-strata"
)

旧想法使用负 ID（-1、-2、-3……），当前想法使用正 ID。两者都可完整搜索——它们位于同一个向量空间中。星群查看器有一个切换选项：点击“THOUGHTS”可淡化当前星点并突出显示历史记录。

CSV 审计日志

每次 Agent 交互都会记录到 data/audit/ 中按日划分的 CSV 文件：

data/audit/
  audit_2026-04-19.csv
  audit_2026-04-20.csv
  ...

每一行记录：

• timestamp — 操作完成的时间（UTC）
• agent_name — 发起调用的 Agent
• agent_key_hint — 遮蔽后的 API 密钥（足以识别，但无法用于调用）
• action — 发生的操作（capture_thought、semantic_search 等）
• detail — 搜索查询或内容预览
• thought_ids — 涉及的想法 ID
• result_count — 返回的结果数量
• response_ms — 操作耗时

通过 REST 查询今天的日志：GET /api/audit?limit=50

覆盖目录：STRATA_AUDIT_DIR=/your/path 完全禁用：STRATA_AUDIT_ENABLED=false

PostgreSQL 后端（生产环境）

SQLite 非常适合入门和单用户配置。对于多个 Agent 同时访问 Strata 的生产环境，请切换到 PostgreSQL：

# Install PostgreSQL 17 + pgvector
sudo apt install postgresql-17 postgresql-17-pgvector

# Create the database and user
sudo -u postgres createuser strata
sudo -u postgres createdb strata_db -O strata
sudo -u postgres psql -c "ALTER USER strata PASSWORD 'your-password-here';"

# Run the schema (creates tables, indexes, triggers)
sudo -u postgres psql -d strata_db -f strata_pg_schema.sql

# Set the backend
export STRATA_DB_BACKEND=postgresql
export STRATA_PG_PASSWORD=your-password-here

# Start Strata — it auto-detects the backend
python server.py

从 SQLite 迁移到 PostgreSQL

如果你已经在 SQLite 中存有想法：

python migrate_to_pg.py

这会迁移所有想法、嵌入向量、历史记录、Agent 密钥和个人资料。你的 SQLite 数据库会保留为备份。

为什么选择 PostgreSQL？

功能	SQLite	PostgreSQL
并发写入者	1（写入队列）	不限
相似度搜索	Python 中的 numpy	数据库内的 pgvector HNSW
全文搜索	FTS5	tsvector（加权）
扩展规模目标	< 10K 个想法	1M+ 个想法
配置复杂度	无	中等

先试用演示（60 秒，无需配置）

仓库自带一个预先填充的演示数据库：包含 666 条关于 Strata 本身的精选想法、3 个带调色板颜色的示例 Agent，可直接探索。无需挖掘数据、寻找种子数据，也不用费心考虑先记录什么——只需克隆仓库，将演示数据库放到指定位置，即可看到已填充内容的星群。

git clone https://github.com/agenerationforwordz-tech/strata.git
cd strata

python -m venv venv
source venv/bin/activate     # Windows: venv\Scripts\activate
pip install -r requirements.txt

# Drop the curated demo dataset into place
mkdir -p data
cp demo/strata.db data/strata.db

# Run with demo mode so blank passwords work for visitors
STRATA_DEMO_MODE=true python server.py

⏱️ 首次安装需要 5–15 分钟。 pip install -r requirements.txt 会为嵌入模型运行时（fastembed、onnxruntime、numpy、transformers 分词器支持）下载约 700 MB 的二进制 wheel。如果安装看起来卡住了，请不要终止——它正在后台下载二进制文件。之后的安装会复用 venv，只需几秒钟。如果想查看字节计数逐渐增加的过程，可以运行 pip install -r requirements.txt --progress-bar on。

在浏览器中打开以下地址：

URL	显示内容
http://localhost:4320/dashboard	Web 仪表板 — 使用空密码登录（演示模式）
http://localhost:4320/constellation	3D 星群查看器，以神圣几何簇的形式展示全部 666 条想法
http://localhost:4320/admin/agents	管理 3 个示例 Agent 的密钥（默认全部禁用——启用其中一个或创建自己的 Agent，即可开始使用 Strata）

请参阅 demo/README.md，了解完整的演示数据集详情，包括如何重新生成自己的数据集。

Windows 安装说明

以下是一些值得了解的 Windows 特有注意事项：

• D: 盘上的 Git“所有权可疑”错误。 如果将 Strata 克隆到 D:\ 或任何非系统盘，Git 可能会拒绝操作该仓库，并报错 fatal: detected dubious ownership in repository。解决方法：

  git config --global --add safe.directory 'D:/Claude Code Projects/strata'
  

  （将路径替换为你克隆到的位置。）
• PowerShell 环境变量使用 $env:，而不是 export。 设置演示模式标志并运行：

  $env:STRATA_DEMO_MODE = "true"
  python server.py
  

  要跨会话持久设置环境变量：

  [System.Environment]::SetEnvironmentVariable('STRATA_DEMO_MODE','true','User')
  

• 过期的 pip 进程可能会在长时间安装期间锁定虚拟环境中的文件。 如果取消安装后重新运行，并遇到权限错误，请通过任务管理器或 Stop-Process -Name python -Force 结束所有残留的 python.exe 进程，然后重试。

开始使用（实际安装，不含演示数据）

git clone https://github.com/agenerationforwordz-tech/strata.git
cd strata

python -m venv venv
source venv/bin/activate  # Linux/macOS
# or: venv\Scripts\activate  # Windows

pip install -r requirements.txt

# Optional: legacy fallback admin key for delete operations.
# In v2, every agent has its own key issued from /admin/agents,
# but this admin key is required for destructive operations.
export STRATA_ADMIN_KEY="different-key-for-delete-ops"

python server.py

⏱️ 与上文相同，首次安装时请注意：pip install -r requirements.txt 会为嵌入模型运行时下载约 700 MB 的二进制 wheel。首次安装请预留 5–15 分钟。

服务启动后，打开 http://localhost:4320/admin/agents 注册你的第一个 Agent。AI 客户端通过各 Agent 专属密钥进行连接——请参阅下文的“连接你的 AI”部分。

服务运行于 http://0.0.0.0:4320。

连接你的 AI

首先，在 http://your-server:4320/admin/agents 注册 Agent 并复制其密钥。每个 Agent 都应使用自己的密钥——这是各 Agent 权限、身份颜色和审计跟踪的实现方式。

Claude Code — 一键安装（推荐）

Strata 以 Claude Code 插件形式提供。添加一次市场源，然后安装：

claude plugin marketplace add agenerationforwordz-tech/strata-plugins
claude plugin install strata@strata-plugins

安装期间，系统会提示你填写两项内容：

• strata_url — 例如，本地安装时使用 http://localhost:4320/mcp
• strata_api_key — 你从 /admin/agents 复制的 Agent 密钥

重启 Claude Code 后，你的 AI 就能在每个会话中使用持久记忆。

Claude Code — 手动配置 MCP（较旧版本）

claude mcp add --transport http strata http://your-server-ip:4320/mcp \
  --header "X-API-Key: agent-your-key-here"

或者添加到 ~/.claude/settings.json：

{
  "mcpServers": {
    "strata": {
      "url": "http://your-server-ip:4320/mcp",
      "headers": {
        "X-API-Key": "agent-your-key-here"
      }
    }
  }
}

Codex CLI

Codex CLI 的 MCP 配置位于 ~/.codex/config.toml（Windows：C:\Users\<you>\.codex\config.toml）。添加以下配置块：

[mcp_servers.strata]
url = "http://your-server-ip:4320/mcp"
env_http_headers = { "X-API-Key" = "STRATA_CODEX_API_KEY" }
startup_timeout_sec = 15.0
tool_timeout_sec = 60

然后设置 env_http_headers 行所引用的环境变量——Codex 会在启动时解析该变量，而不是在加载配置时解析：

Linux/macOS：

export STRATA_CODEX_API_KEY="agent-your-codex-key-here"

Windows（跨会话持久设置）：

[System.Environment]::SetEnvironmentVariable('STRATA_CODEX_API_KEY','agent-your-codex-key-here','User')

使用以下命令验证：

codex mcp get strata

你应该会看到 enabled: true 的条目。

⚠️ 已知的 Codex CLI 问题（截至 Windows 上的 v0.120.0）： 可流式传输的 HTTP 传输方式可以正确发现 Strata 的工具，但 codex exec 可能会在客户端取消实际的工具调用，并显示 user cancelled MCP tool call。这似乎是 Codex CLI 的错误，而非 Strata 的问题——Strata 服务日志显示 MCP 请求返回了 200 OK。如果遇到此问题，请向 Codex CLI 仓库报告。同一 Strata 服务可与 Claude Code、仪表板和直接 REST 调用正常配合使用。

Agent 如何学会使用 Strata

每个已连接的 Agent 都应将 strata_status 作为首次工具调用。该工具会返回一段自然语言协议，教 Agent 何时捕获、何时搜索、如何处理 10 种思维类型，以及如何解读负 ID 的旧版导入数据。无需配置 CLAUDE.md——该工具会自行提供指导。

管理员可以通过仪表板或 REST 端点向 system_config['agent_protocol'] 行写入内容，按实例自定义协议：

curl -X PUT http://your-server:4320/admin/api/protocol \
  -H "X-API-Key: $STRATA_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"protocol": "...your custom instructions..."}'

发送空字符串即可重置为默认值。

任意 HTTP 客户端

# Save a thought
curl -X POST http://your-server:4320/api/capture \
 -H "Content-Type: application/json" \
 -H "X-API-Key: your-key" \
 -d '{"content": "STRATA is running on my Pi!", "tags": ["setup"]}'

# Search by meaning
curl -X POST http://your-server:4320/api/search \
 -H "Content-Type: application/json" \
 -H "X-API-Key: your-key" \
 -d '{"query": "server setup", "limit": 5}'

# Health check (no auth needed)
curl http://your-server:4320/health

配置

所有配置都在 config.py 中。可通过环境变量覆盖：

变量	默认值	作用
STRATA_API_KEY	change-me-before-deploy	旧版 REST 密钥的备用值
STRATA_ADMIN_KEY	(为空 - 禁用删除操作)	执行删除和管理操作所需
STRATA_HOST	0.0.0.0	监听地址
STRATA_PORT	4320	服务端口
STRATA_DATA_DIR	./data	数据库位置
STRATA_VAULT_DIR	./data/vault	文件库位置
STRATA_AUTH_ENABLED	true	认证总开关（不要关闭）
STRATA_MAX_TOTAL_AGENTS	10	已注册 Agent 总数的反垃圾上限
STRATA_DEMO_MODE	(未设置)	若为 true，仪表板允许使用空密码（公开演示）
STRATA_DB_ENCRYPT	(未设置)	若为 true，通过 SQLCipher 打开数据库（请先运行 setup_encryption.sh）
STRATA_DB_KEY_FILE	/etc/strata/db.key	SQLCipher 密钥文件路径（仅限 root/strata）
STRATA_IP_AGENTS	(为空)	以逗号分隔的 IP=name 对，用于旧版 IP→Agent 归属映射

工具（21 个核心工具 + 扩展）

记忆

工具	作用
capture_thought	保存一条新记忆，并自动添加标签和检查重复项
semantic_search	按含义查找记忆
hybrid_search	结合关键词和含义进行搜索
search_by_tag	按标签筛选
search_by_person	按提及的人物筛选
search_advanced	组合筛选条件：标签 + 类型 + 日期 + 机器
get_relevant_context	智能搜索——去重并按类型分组 (扩展)
find_related	查找与指定想法相似的内容
list_recent	查看最近捕获的内容
get_thought	查看一条想法（包括其文件附件）
update_thought	编辑一条想法（自动重新生成嵌入向量）
delete_thought	删除一条想法及其库中文件（需要管理员密钥）
get_stats	数据库统计信息和文件库用量
generate_report	趋势报告——显示哪些内容在增加、哪些在减少 (扩展)

文件库

工具	作用
attach_file	为一条想法添加文件
get_file	读取已附加的文件
list_attachments	查看一条想法上的所有文件
detach_file	移除一个附件（需要管理员密钥）

Web 仪表板

STRATA 在 http://your-server:4320/dashboard 提供完整的 Web 仪表板。无需额外设置——首次访问时会引导你创建账户。

账户系统

• 密码保护——首次访问时设置密码以创建账户（PBKDF2-SHA256，480K 次迭代）
• 12 个单词的恢复短语——设置期间生成，类似 Bitcoin 钱包。请记下来。这是重置遗忘密码的唯一方法。系统只存储其哈希值，从不以明文存储。
• 设备会话——每个浏览器都会获得一个命名会话（如“my-laptop”“my-phone”）。不同设备的名称必须唯一。会话有效期为 7-365 天（由你选择）。
• 10 天重命名冷却期——设备名称每 10 天只能更改一次，以防滥用
• 设置页面——更改密码（需要当前密码）、查看已连接设备、重命名设备

AI 客户端（Claude Code、Codex 等）仍通过 X-API-Key 标头使用 API 密钥。仪表板认证是独立系统，两者互不影响。

仪表板功能

• 捕获想法：在浏览器中记录想法，并添加标签、人物和类型
• 语义搜索：按含义而非关键词查找
• 标签搜索：点击任意标签，即可筛选带有该标签的所有想法。在搜索栏中输入 #tagname 也能实现相同效果。
• 无限滚动：每次加载 30 条想法，并在滚动时获取更多内容
• 统计卡片：记忆总数、标签数量、提及的人物、数据库大小
• 热门标签：展示正在上升、下降和新出现的标签，并支持点击筛选
• 设备活动：通过动态条形图展示贡献最多的设备
• 最热门记忆：按访问次数排列最常访问的想法
• 深色主题：温暖的深色模式，适配移动设备

每个 Agent 独立的 API 密钥

在 v1 中，所有 AI 工具共用一个 STRATA_API_KEY。当“所有 AI 工具”只有你和 Claude Code 时，这样做没问题。但只要你有一台 Surface 笔记本电脑、一台 Helios 台式电脑、几个 telegram 机器人，以及一个每晚运行的 cron 作业都在访问 Strata，你就会想知道每个 Agent 做了什么，也会希望能够撤销其中任意一个 Agent 的访问权限，而不影响其他 Agent。

v2 提供了每个 Agent 独立的密钥。打开 /admin/agents，点击“Register New Agent”，为其命名，即可获得一个唯一密钥，例如 agent-G8O1bK2kQiN3F0Haq03e_0kIh5D8YiFo。Agent 在 X-API-Key 标头中使用该密钥——server.py 会在每次请求时查找密钥，并检查细粒度的权限标志。

权限	控制内容
enabled	总开关——停用 Agent，但不删除它
can_read	semantic_search、list_recent、get_thought 等
can_write	capture_thought、update_thought、附加文件
can_delete	delete_thought、detach_file（默认关闭）
can_admin	管理其他 Agent、查看审计数据
can_kill	触发全局 MCP 紧急停用开关（见下文）

专用的人类管理员密钥（STRATA_ADMIN_KEY）始终独立存在，绝不会出现在 Agent 表格中。它是用于执行任何 Agent 都不应自行操作的任务的主控密钥——重新启用紧急停用开关、向其他 Agent 授予管理员权限、提高活跃 Agent 上限。

全局 MCP 紧急停用开关

只需切换一次，即可禁止所有 Agent 访问 MCP、REST 和 /api/*。可从 /admin/agents（顶部的大型盾牌面板）操作，也可通过 REST 操作：

curl -X PUT http://your-server:4320/admin/api/mcp-toggle \
 -H "X-API-Key: your-agent-or-admin-key" \
 -H "Content-Type: application/json" \
 -d '{"enabled": false}'

权限模型有意采用不对称设计：

• 停用——任何人类管理员，或具有 can_write=1 或 can_kill=1 权限的 Agent 都可以操作。这是一道安全阀。如果 Agent 发现自己遭到入侵，它必须能够直接拉下紧急制动开关，而不必先请求人类授予管理员权限。
• 重新启用——仅限人类管理员密钥。关闭开关的 Agent 不能撤销自己的决定。人类需要亲自切换开关，将其重新打开。

紧急停用开关关闭时，所有 /mcp、/sse 和 /api/* 请求都会返回 503 Service Unavailable。审计日志会记录是谁切换了开关（[KILL SWITCH] Global MCP access DISABLED by claude-on-surface）。星群查看器会实时反映此状态——见下文。

星座视图

打开 http://your-server:4320/constellation，观看你的大脑如何思考。这是数据库中每个想法的 3D 可视化，它们分布在斐波那契球面上，每个集群都会吸附到正十二面体的顶点。背景是一幅生命之花画布——默认几乎不可见，可通过滑块调整。神圣几何，贯彻到底。

当 Agent 搜索或捕获内容时，星座会亮起该 Agent 的颜色，光束则从 Agent 徽章流向每个匹配的想法。每个 Agent 的颜色都存储在数据库中（可在管理面板中编辑），因此视图始终能反映当前身份。

当 MCP 急停开关关闭时，整个场景会褪成银灰色，自动旋转速度降至约 15%，并在中央显示“MCP DISCONNECTED”覆盖层，同时以该执行者的身份颜色显示其名称。从房间另一端也能一眼看清。

将其用作壁纸：http://your-server:4320/constellation?mode=wallpaper 会移除 UI，并让星座全屏运行。

静态数据加密（可选）

默认情况下，Strata 会将 SQLite 数据库存储为普通文件。对于安装在你所控制的 NAS 上的个人实例，这没有问题；但如果你的威胁模型包括“有人拿走了硬盘”或“备份泄露”，你就需要对静态数据进行加密。

sudo ./setup_encryption.sh

该脚本会：

1. 安装 sqlcipher 和 pysqlcipher3 Python 绑定
2. 生成一个 256 位 AES 密钥，并将其保存到 /etc/strata/db.key（模式为 400，仅限 root 访问）
3. 通过 sqlcipher_export() 原地迁移现有数据库
4. 在 systemd 服务中设置 STRATA_DB_ENCRYPT=true 和 STRATA_DB_KEY_FILE=/etc/strata/db.key

重启后，db.py 会通过 pysqlcipher3 而非 sqlite3 打开数据库，且每个查询都会针对 AES 加密页面运行。密钥不会存放在代码或环境变量中——只会存放在 root 所有的文件中。

如果丢失密钥，数据库将无法恢复。 请将密钥备份到安全的地方。

如需取消加密（默认状态），无需执行任何操作。除非设置了 STRATA_DB_ENCRYPT=true，否则加密代码路径不会启用。

文件级访问加固（可选）

即使启用了 API 密钥系统，任何能够通过 SSH 访问主机的人仍可直接用 sqlite3 打开 strata.db，绕过所有身份验证、速率限制和审计跟踪。setup_secure.sh 会堵住这个漏洞：

sudo ./setup_secure.sh

该脚本会：

1. 创建专用的 strata 系统用户（不可登录、无主目录）
2. 将数据目录的所有权设为 strata:strata，权限模式设为 700
3. 将每个数据库文件的权限模式设为 600（仅所有者可读写）
4. 更新 systemd 服务，使其以 strata 用户身份运行

重启后，Strata 进程可以读写数据库，但其他用户（包括 nacho，以及未显式提权的 root）都无法直接操作该文件。所有访问都必须通过 API 进行——这意味着速率限制、身份验证检查和审计日志会统一生效。

演示模式

在会议上的公开演示、展位平板电脑或面向公众的网址上，你不会希望身份验证界面把访客挡在外面。在服务器环境中设置 STRATA_DEMO_MODE=true 后：

• 登录界面仍会显示（访客可以看到系统启用了身份验证）
• /api/auth/setup 和 /api/auth/login 都接受空密码
• 服务器会替换为固定的内部占位密码，以确保哈希、会话和设备名称处理流程正常运行

这仅供演示使用。切勿在真实部署中设置此项——它会彻底移除身份验证屏障。

STRATA_DEMO_MODE=true python server.py

作为服务运行

创建 /etc/systemd/system/strata.service：

[Unit]
Description=STRATA Memory Server
After=network.target

[Service]
Type=simple
User=your-user
WorkingDirectory=/path/to/strata
ExecStart=/path/to/strata/venv/bin/python server.py
Environment=STRATA_API_KEY=your-secret-key
Environment=STRATA_ADMIN_KEY=your-admin-key
Environment=STRATA_DATA_DIR=/path/to/your/data
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable strata
sudo systemctl start strata

构建方式

AI Clients (Claude Code, Codex, bots)          Humans (browser/tablet)
        |                    |                       |
   MCP (/mcp)          REST (/api/*)          Dashboard (/dashboard)
        |                    |                  Constellation (/constellation)
        |                    |                  Admin (/admin/agents)
        |                    |                       |
        +---- MCPKillSwitchMiddleware (rejects all when off) -----+
        |                    |                       |
        +-------- server.py - rate limiting, sanitization --------+
        |                    |                       |
   Per-agent keys      Per-agent keys        Password + session auth
   (X-API-Key)         (X-API-Key)           (auth.py - PBKDF2, seeds)
   agent_keys.py       agent_keys.py         users + sessions tables
        |                    |                       |
   embedder.py          vault.py            activity_stream (SSE)
   ONNX model         file storage          per-agent broadcasts
   on-demand          by device/month                |
        |                    |                       |
              db.py - SQLite (or SQLCipher) + FTS5 + numpy
              thoughts + attachments + users + sessions + agent_keys

硬件

专为 Raspberry Pi 4B（4GB）打造。实际资源占用如下：

项目	RAM
服务器空闲	~50MB
已加载嵌入模型	~100-150MB
10K 个想法	向量约占用 ~30MB

需要时加载模型，空闲 5 分钟后卸载。

存储

内容	磁盘空间
Python venv（fastembed、numpy、onnxruntime）	约 700MB
ONNX 模型（首次使用时下载）	约 170MB
代码 + 仪表板	约 1MB
数据库	每条想法约 1KB

全新安装需要约 1GB 磁盘空间。16GB SD 卡绰绰有余。数据库和文件库会随使用而增长，因此如果你计划附加大量文件，请将文件库指向外部存储。

最低配置：任意配备 2GB RAM、2GB 可用磁盘空间和 Python 3.10+ 的机器。

安全性

• 每个 Agent 使用独立密钥 - 每个 AI Agent 都有自己的密钥，并具有细粒度的 read / write / delete / admin / kill 标志。可撤销或禁用任意一个，而不会影响其他 Agent。
• MCP 全局终止开关 - 只需切换一次，即可禁止所有 Agent 访问。权限不对称：Agent 可以禁用，只有人类可以重新启用。
• 仪表板身份验证 - PBKDF2-SHA256，480K 次迭代，随机 32 字节盐值，恒定时间比较
• 12 个单词的种子短语恢复 - 经哈希处理并永久存储，绝不以明文形式保存
• 会话令牌 - 256 位随机值，存储在 SQLite 中，自动过期，按设备区分
• 审计日志 - 每次切换终止开关都会记录操作方的 Agent 名称
• 静态加密（可选） - SQLCipher AES-256，密钥存放于仅 root 可访问的文件中（setup_encryption.sh）
• 文件级加固（可选） - 专用系统用户 strata 以 600 权限拥有数据库（setup_secure.sh）
• 破坏性操作（删除/分离）使用单独的管理员密钥
• 速率限制 - 每个 IP 每分钟 30 个请求
• 输入大小限制 - 每条想法 50KB，每个文件库文件 1GB
• 提示词注入防护 - 将内容包装为数据标记，供 AI 客户端使用
• XSS 防护 - 渲染前转义所有用户内容
• 原子文件写入 - 临时文件 + 重命名，断电时不会产生不完整文件
• 对所有文件库操作进行路径遍历防护
• 代码库中任何地方都不使用 eval/exec
• 核心无需额外运行时依赖 - 身份验证仅使用 Python 标准库；SQLCipher 和 setup_*.sh 脚本均为可选

扩展

STRATA 支持可选的 extensions.py 文件，用于注册额外的 MCP 工具和 REST 端点。你可以通过这种方式为部署添加自定义功能，而无需修改核心服务。

如果项目目录中存在 extensions.py，服务会在启动时自动加载。如果该文件不存在，服务仍可正常运行，提供 16 个核心工具。

上表中标记为 (扩展) 的工具可通过扩展功能使用。文档中列出了这些工具，让你了解可实现的功能，但本仓库不包含其实现。创建自己的 extensions.py，并添加 register_extensions() 函数，即可添加自定义工具。

许可证

PolyForm Noncommercial License 1.0.0。Copyright (c) 2026 A Generation Forwordz Foundation.

STRATA 是源代码可用软件。你可以使用、改进、分享和学习，但请保持免费并注明出处。请勿出售。

如需咨询商业许可，请联系 A Generation Forwordz Foundation。

详情请参阅 LICENSE。

---

由 Christian Mitchell 构建。如果你使用此项目，请保留署名。