Space

Space

Space 是一个由你和 AI Agent 共享的工作区：包含文档、任务、数据库和长期记忆，Agent 可通过 MCP 读取和写入；网站则让你查看、纠正和编辑同一份内容。连接 Claude Code、Codex、Cursor 或任何 MCP 客户端，一个会话学到的内容会留给下一个会话。

此仓库是开源、可自托管的版本。它通过 Docker Compose 运行在你控制的一台机器上，例如小型 VPS。无需云账户：不需要托管数据库、对象存储、密钥服务或登录提供商。

你将获得

• 文档和任务，包含完整的修订历史，可通过网站或 Agent 编辑。
• 数据库：类型化表格和看板，Agent 可使用 SQL 查询和修改。
• Agent 记忆：会话之间的交接，以及 Agent 会记住的声明；Agent 可通过引用进行回忆、纠正和遗忘。
• 在整个 Space 中按关键词搜索和回忆；配置模型提供商后，还可按含义搜索和回忆。
• 一个 MCP 端点供所有 Agent 使用；每个 Agent 都有可撤销的令牌或浏览器登录，并可追溯内容由谁撰写。
• 一个 REST API，支持个人 API 密钥；数据库行发生变化时会发送已签名的 Webhook。
• Agent 新建内容时会遵循的项目、文件夹、分区和类别。

构建方式

部分	运行内容
caddy	唯一对外发布的服务。提供带自动证书的 HTTPS，并路由请求。
web	网站（基于 Node.js 的 TanStack Start）。
api	REST API 和 MCP 端点（Python、FastAPI）。
worker	在后台提取记忆。
webhooks	发送已签名的 Webhook。
db	PostgreSQL 17 和 pgvector。所有文档、任务、记忆和设置都存储在这里。

内容以可读的 JSON 格式存储在 PostgreSQL 中。应用层不提供加密：运行服务器的人可以读取数据，这和任何自托管应用一样。请备份数据库并采取相应措施保护服务器。

安装

你需要一台至少有 1 GB 内存的 Linux 服务器，例如小型 VPS；如需公开访问，还需要一个 DNS 记录指向该服务器的域名。在服务器上运行：

curl -fsSL https://raw.githubusercontent.com/Hugo-SEQUIER/getspace/main/scripts/install.sh | sudo bash

如果尚未安装 Docker，安装程序会先安装；随后将最新版本下载到 /opt/space，询问访问模式、域名和你的姓名，启动 Space，并显示其地址和访问密钥。要手动执行相同步骤：

git clone https://github.com/Hugo-SEQUIER/getspace.git
cd getspace
git checkout "$(git tag -l 'v*' | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -n 1)"   # latest release
scripts/setup.sh                 # asks for the access mode and your domain, writes .env
docker compose up -d             # downloads the released images and starts everything
docker compose exec api python -m space.check   # checks every setting, in plain words

两种方式都提供以下访问模式：

• 密钥模式（默认）：可通过 https://your-domain 从互联网访问 Space。网站会要求每个浏览器输入一次实例的访问密钥，每个 Agent 则使用自己的可撤销令牌进行连接。将 DNS 记录指向服务器并开放 80 和 443 端口；Caddy 会获取证书。
• 私有模式：完全不进行访问检查。Space 监听 127.0.0.1:8080，你可通过 SSH 隧道或 Tailscale 等 VPN 访问。切勿将此模式公开到互联网上。

没有用户账户：每个安装实例属于一个人，即所有者。自托管文档介绍了两种模式、所有设置、升级、备份和故障排除。

要从托管版 Space 迁移？先在托管版中导出 Space，再导入到这里：从托管版 Space 迁移。

连接 Agent

在网站上打开Agent → 连接 Agent，选择名称和 Agent 是否可以写入，然后复制页面显示的配置。对于 Claude Code：

claude mcp add --transport http space https://your-domain/mcp/ \
  --header "Authorization: Bearer spc_..."

claude.ai 和 ChatGPT 等托管式助手则通过登录连接：将 https://your-domain/mcp/ 作为自定义连接器添加到应用中，并在它于浏览器中打开 Space 时批准连接。

在私有模式下，Agent 无需令牌：claude mcp add --transport http space http://127.0.0.1:8080/mcp/。连接 Agent提供了 Codex、Cursor 和其他客户端的配置方法；可选的Agent 技能则会指导 Agent 何时回忆、记忆和交接。

使用模型提供方的记忆

文档、任务、数据库、交接和文字搜索无需任何模型即可使用。自动记忆（从文本中提取声明、生成嵌入向量和语义召回）需要兼容 OpenAI 的端点或 Ollama；请在 .env 中设置 SPACE_MEMORY_PROVIDER 和相关配置。只有 Agent 要求 Space 处理的文本才会发送给该提供方。OpenRouter 的 Decisions API 上的决策模型还可以评估召回证据、根据你的类别和项目整理记忆，并关联相关记忆；这些功能默认均为关闭状态，需手动启用。请参阅记忆。

备份和升级

scripts/backup.sh                                  # writes backups/space-<time>.dump
scripts/upgrade.sh                                 # backs up, then moves to the latest release
scripts/restore.sh backups/space-<time>.dump       # replace this installation's data

将备份复制到服务器之外：存放在同一磁盘上的备份不算备份。

文档

文档	涵盖内容
自托管	安装、访问模式、配置、升级、备份、安全和故障排除。
从托管版 Space 迁移	导出托管版 Space，并将其导入自己的安装实例。
连接 Agent	令牌、客户端设置、Agent 身份和设备代码流程。
架构	进程、存储、访问控制和后台工作。
开发	从源代码运行、测试和检查。
MCP	Agent 接口及其工具。
记忆	交接、声明、召回和声明索引。
Webhooks	数据库行发生变化时发送的签名通知。
术语表	系统使用的所有术语。
API 参考	个人 API 密钥可调用的 REST API（OpenAPI）。

许可证

Space 是基于 GNU Affero 通用公共许可证 v3.0 发布的自由软件。你可以出于任何目的使用、修改和自托管。如果你通过网络向他人提供修改后的版本，就必须向他们提供其源代码。随附的 Memora 运行时仍采用其 MIT 许可证；请参阅 NOTICE 和 THIRD-PARTY.md。

欢迎贡献。请阅读 CONTRIBUTING.md，并在首次提交拉取请求前接受贡献者许可协议。