aperio (Bai Ganio)

✨ Aperio

一个大脑。每个特工。什么都没忘记。\ AI代理的自托管个人记忆层。Docker+Postgres+pgvector+MCP+Ollama。\ 您的上下文，始终可用。

• Getting Started • Architecture • Philosophy • AI Providers • How To Use? • Privacy • Security • Design Decisions •

• 🌐 地点： •

](https://github.com/baiganio/aperio/releases)

    ](https://app.codacy.com/gh/BaiGanio/aperio/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)  

💡 Pro Tip: Visit How to Install & Use Aperio‐lite? for extensive installation instructions. --> 💡 Pro Tip: Visit the Aperio Wiki or Discussions for extensive documentation on advanced topics.

🔍 Explore more: Early Testing Contributors • FAQ • Troubleshooting

______________________________________________________________________

🏗️ （快速）项目结构

📂 aperio/           **💡 提示：** **`whoami.md`** 控制AI代理的身份。
>
> - 这是最有影响力的自定义文件。

______________________________________________________________________

## 入门指南

### 先决条件

- Node.js 18+-从下载 
-  --（可选，用于Postgres模式）
- Ollama--下载  （可选，适用于本地AI）
- [无烟煤API键](https://console.anthropic.com) --（可选，适用于云AI）
- [DeepSeek API密钥](https://platform.deepseek.com) --（可选，适用于云AI）
- [Voyage AI API键](https://www.voyageai.com/) --（可选，用于云嵌入）

### 步骤1。克隆和配置环境变量

专注 `dev` 分支从文件/文件夹中去除噪声。只有需要的东西。

dedicated developer branch - no extra files

git clone --depth 1 -b dev https://github.com/BaiGanio/aperio.git cd aperio

restore dependencies

npm install

> 随时可用 `.env.example` 对于完全本地设置：

cp .env.example .env

DATABASE_URL=postgresql://aperio:aperio_secret@localhost:5432/aperio AI_PROVIDER=ollama OLLAMA_MODEL=qwen2.5:3b EMBEDDING_PROVIDER=transformers # fully local, no API key required

### 步骤2。数据库和迁移

Aperio支持两个矢量存储后端——选择一个适合您的设置：

|后端|何时使用|需要|
|---------|-------------|----------|
| **兰斯数据库** （默认）|无Docker，快速启动，单用户|无需额外设置|
| **Postgres+pgvector** |多代理、持久、类似生产|Docker|

LanceDB is the default — no extra steps needed.

Skip the Docker commands below and go directly to Step 3.

> **💡 提示：** 集 `DB_BACKEND=lancedb` 在 `.env` 强制LanceDB，或 `DB_BACKEND=postgres` 对于Postgres来说。\
> 如果没有设置，Aperio会自动检测：在Docker运行时使用Postgres，否则使用LanceDB。

POSTGRES MODE — start the database and run migrations

cd docker && docker compose up -d && cd ..

- MacOS/Linux

docker exec -i aperio_db psql -U aperio -d aperio 💡 提示： 如果您使用Anthropic或DeepSeek作为您的 AI_PROVIDER.

ollama serve                     # use separate terminal

ollama pull qwen2.5:3b           # LLM — lightweight, fast, good tool-calling
# ollama pull llama3.1           # LLM — solid tool-calling, no reasoning
# ollama pull qwen3:4b           # LLM — strong reasoning, thinking mode support

步骤4。启动Aperio Web用户界面

npm run start:local              # localhost:31337 → browser opens automatically

步骤5。开始Aperio终端聊天

npm run chat:local               # runs as proxy or standalone

就是这样，没有API密钥。没有云。机器上的完整语义记忆。

Q： 现在怎么办？

💡 安装步骤受阻？--检查 故障排除 维基。

💡 检查 Aperio MCP工具指南 wiki提供了扩展示例。\ 💡 检查 命令 wiki提供运行应用程序的可用选项。

[Back to top ↑]

______________________________________________________________________

建筑

Q： 你觉得有必要阅读吗？

💡 提示： 访问 建筑与设计 为了 彻底的 解释。

[Back to top ↑]

______________________________________________________________________

MCP工具

Aperio曝光 13工具 通过MCP。任何与MCP兼容的代理（Cursor、Windsurf、Claude等）都可以调用它们。

💡 提示： 检查 Aperio MCP工具指南 用于呼叫示例。

[Back to top ↑]

______________________________________________________________________

哲学

Aperio是开源和自托管的，因为 你的记忆属于你.

• 它完全在你的机器上运行——没有API密钥，没有数据离开你的网络，没有云依赖。
• 默认设置为本地和私有。选项-自托管。价格永远免费。
• Cloud AI可作为电源升级，但您永远不会被迫使用它。

| | |---| | ✅ 自由奔跑 | | |没有订阅。无每条消息的成本。只是你的硬件。 | |

#### ‼️ Aperio不是什么！

[Back to top ↑]

______________________________________________________________________

AI提供商

使用单线进行切换 .env其他一切——记忆、工具、用户界面——都保持不变。

AI_PROVIDER=ollama       # "ollama" | "anthropic" | "deepseek"

⬡ Ollama（默认--本地、免费、私人）

没有API密钥，没有数据离开您的机器。

AI_PROVIDER=ollama
OLLAMA_MODEL=qwen2.5:3b
OLLAMA_BASE_URL=http://localhost:11434

推荐型号（搭配 ollama pull ):

💡 提示： 集 CHECK_RAM=true 在 .env 让Aperio根据可用RAM自动选择型号。

✦ 拟人克劳德（可选——云升级）

用于繁重的研究、复杂的多步骤推理或可用的最强工具调用。

AI_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...
ANTHROPIC_MODEL=claude-haiku-4-5-20251001

可用型号（通过设置 ANTHROPIC_MODEL):

◈ DeepSeek（可选——云升级）

具有强大推理能力的经济高效的云替代方案。

AI_PROVIDER=deepseek
DEEPSEEK_API_KEY=sk-...
DEEPSEEK_MODEL=deepseek-chat

注册地址： platform.depeseek.com。无视觉支持——在DeepSeek模式下禁用图像工具。

______________________________________________________________________

嵌入

嵌入可以在你的记忆中进行语义搜索。Aperio支持两个提供商：

EMBEDDING_PROVIDER=transformers   # "transformers" | "voyage"

拥抱面变压器（默认--完全本地）

下载 mixedbread-ai/mxbai-embed-large-v1 （ONNX，量化）首次运行。没有守护程序，没有API密钥，初始下载后没有网络调用。

EMBEDDING_PROVIDER=transformers

Voyage AI（可选——云）

更高质量的嵌入，免费等级：每月5000万代币。

EMBEDDING_PROVIDER=voyage
VOYAGE_API_KEY=pa-...

注册地址： 网站 dash.voyageai.com.

Q： 就这些吗？

[Back to top ↑]

______________________________________________________________________

隐私

使用本地AI读取文件

Ollama本身没有文件系统访问权限，它纯粹是一个推理引擎。 Aperio的MCP层弥合了这一差距。

当你要求AI读取文件时，实际情况如下：

You       →  "read /path/to/server.js and explain the WebSocket handler"
MCP Server →  calls read_file tool, loads the file from disk
Ollama    →  receives the file contents as context, reasons over it
You       ←  answer based on your actual code

该模型从不直接接触您的文件系统。 Aperio读取文件并将内容注入到对话中。

Q： 你管这叫隐私？

💡 查看我们的wiki页面 MPC工具 了解更多详情。

[Back to top ↑]

______________________________________________________________________

安全

Aperio在您的计算机上运行，并通过 scan_project, write_file, append_file，以及 read_file 工具。文件操作由路径安全系统控制——读写访问是独立控制的。

文件系统访问

所有文件操作都会执行 lib/routes/paths.js，它在每个路径到达磁盘之前对其进行解析和验证。

两个环境变量控制着可访问的内容：

# Allow read operations only inside these directories (comma-separated absolute paths)
APERIO_ALLOWED_PATHS_TO_READ=/Users/yourname/projects,/Users/yourname/documents

# Allow write operations only inside these directories (comma-separated absolute paths)
APERIO_ALLOWED_PATHS_TO_WRITE=/Users/yourname/projects

路径解析的工作原理：

1. 这两个值默认为当前工作目录(process.cwd())当未设置时——这是运行Aperio项目时的根目录 npm run start:local.
2. 路径在启动时解析为绝对形式。 ~ 扩展到工作目录。
3. 读或写请求 /some/path/file.txt 仅当其解析的绝对路径以允许的目录之一开头时才允许。在发生任何I/O之前，允许列表之外的路径将被拒绝，并显示一条明确的错误消息。
4. 读写保护是分开的。您可以授予广泛的读取权限，同时保持狭窄的写入权限——例如，读取整个 ~/projects 树，但只写在Aperio项目根内。

模型能做什么和不能做什么：

另外， read_file 强制执行：

• 扩展允许列表 --只有代码和文本文件(.js, .ts, .py, .md, .json, .sql, .sh等等）
• 尺码上限 --大于500 KB的文件被拒绝
• 分页 --每次通话最多读取500行；使用 offset 用于浏览较大文件的参数

📄 记笔记：

• 仅在您信任的机器上运行Aperio
• 未经身份验证，请勿将MCP服务器或web UI暴露于公共互联网
• 在确认之前，请先检查任何文件写入操作-- write_file 完全覆盖，不撤消
• 人工智能模型可以被提示（或产生幻觉）写入敏感路径——在确认之前一定要进行审查
• 永远不要承诺你的 .env 文件-它包含您的数据库URL和API密钥
• 写入路径应等于读取路径或读取路径的严格子集

Q： 就这些？

💡 查看我们的wiki页面 路径安全 了解更多详情。

[Back to top ↑]

______________________________________________________________________

一个大脑。每个特工。什么都没忘记。

*来自拉丁语* 打开 *--打开、揭示、带入光明。*