Ai-Memory-Free

# Ai-Memory-Free **当前版本：v1.2.0 — 协议 v1，八个独立可发现的模块。** [](LICENSE) [](docs/FAQ.md#is-ai-memory-free-really-free) [](docs/MCP.md) **将此仓库链接提供给任何有能力的 AI 编程代理：** <https://github.com/BizrnrAI/Ai-Memory-Free> 可粘贴的提示在 [INSTALL_WITH_AI.md](INSTALL_WITH_AI.md) 中。完整的模型中立实现合同在 [docs/AI_AGENT_INSTALL.md](docs/AI_AGENT_INSTALL.md)。 由 [Kristian Peter](https://kristianpeter.com) 创建，首席自动化官。 在 [MIT License](LICENSE) 下免费使用：无需许可费、账户或付费模型 API。 Ai-Memory-Free 是一个无成本、LLM 无关的代理、应用程序和 MCP 客户端的内存服务。它在单个 Supabase Postgres 数据库中存储持久平台知识，并返回排名上下文，而无需任何生成模型进行推理、总结或重写。 默认路径提供： - 混合 pgvector + 全文检索，带有透明的 Reciprocal Rank Fusion - 免费的边缘 `gte-small` 嵌入，带有有界的多块平均 - 命名空间、标签、元数据、来源、退休和继承 - 不变的排名重要性 + 单独的生命周期衰减 - 精确的重复预防和可选的语义压缩 - 哈希的、可撤销的、过期的 API 凭证，带有每个客户端的权限 - 在每次读取或写入之前强制执行的命名空间隔离 - 基于数据库的每个客户端速率限制和安全审计事件 - 使用 Supabase Vault 认证加密的可恢复平台机密 - 一个 HTTPS API、一个 TypeScript 客户端和一个薄的 MCP 适配器 - 具有明确字符预算的确定性多命名空间上下文包 - 幂等批量摄入和可选的追加写入代理活动日志 - 一流的源置信度、 freshness、有效性和矛盾证据 - 便携的校验和导出/导入，排除凭证并重新生成向量 - 可插拔的嵌入配置文件，同时保留免费的 `gte-small` 作为默认值 - 可选的文档/块搜索、维护状态和 OAuth 保护的远程 MCP - 单元测试、Deno 测试、迁移检查和检索评估 fixtures - 无需付费模型 API、托管向量数据库、队列或始终在线的服务器 调用者提供 LLM。该服务仅存储和检索可检查的数据，因此 Claude、Codex、Gemini、本地模型、普通软件和未来的代理都可以共享相同的内存。 ## 选择您的路径 | 目标 | 从这里开始 | | --- | --- | | 将 GitHub 链接提供给 AI 代理 | [INSTALL_WITH_AI.md](INSTALL_WITH_AI.md) | | 部署新的内存后端 | [AI 代理安装合同](docs/AI_AGENT_INSTALL.md#path-a-deploy-a-new-independent-memory) | | 连接现有仓库 | [现有项目路径](docs/AI_AGENT_INSTALL.md#path-b-connect-an-existing-project-or-repository) | | 配置 MCP | [MCP 指南](docs/MCP.md) | | 了解 v1.2 模块 | [模块合同](docs/MODULES.md) | | 从 v0.2 升级 | [v1.2 升级指南](docs/UPGRADE_V1_2.md) | | 在安装之间移动数据 | [便携式导出/导入](docs/PORTABILITY.md) | | 从 TypeScript 或 HTTPS 调用 | [集成选择](docs/AI_AGENT_INSTALL.md#integration-choices) | | 了解安全性和 Vault | [安全模型](docs/SECURITY.md) | | 浏览所有文档 | [文档索引](docs/INDEX.md) | 该项目是自我部署的。您的 Supabase 账户拥有数据库、内存、令牌和 Vault 机密。该仓库不会向 KristianPeter.com 或 BizRnR 发送任何 telemetry。 ## 凭证语义 外部调用者令牌是高熵身份验证凭证。只有它们的 SHA-256 哈希被存储，因此数据库泄漏不会产生可用的 bearer 令牌。 平台 API 密钥和机密有不同的要求：授权服务可能需要恢复它们。它们通过 Supabase Vault 存储，Supabase Vault 应用认证加密并将加密密钥保留在数据库之外。机密永远不会进入语义内存、嵌入、全文搜索、元数据列表或审计日志。 ## 架构 ```text 任何 LLM / 代理 / 应用程序 | | 有范围的 bearer 令牌 v Supabase 边缘函数 身份验证 -> 命名空间/权限门 -> 速率限制 -> 操作 -> 审计 | | | +-> Supabase Vault 加密机密 v Postgres 内存 -> 向量 + 全文检索 + RRF -> 排名上下文 ^ | stdio MCP 适配器（可选的秘密工具默认关闭） ``` ## 快速入门 1. 克隆仓库，创建一个免费的 Supabase 项目，并安装 Supabase CLI： ```bash git clone https://github.com/BizrnrAI/Ai-Memory-Free.git cd Ai-Memory-Free ``` 2. 安装锁定的 Node 依赖项： ```bash npm ci ``` 3. 链接项目并应用已审查的迁移： ```bash supabase link --project-ref YOUR_PROJECT_REF supabase migration up --linked ``` 对于共享或生产项目，请使用正常的受控迁移过程。永远不要直接应用未经审查的 SQL。 4. 生成高熵客户端令牌及其 SHA-256 数据库表示： ```bash npm run token:create -- \ --name primary-agent \ --namespaces platform \ --permissions memory:read,memory:write ``` 将显示的令牌保存在您的客户端机密存储中，然后在 Supabase SQL 编辑器中运行显示的 SQL。只有哈希值被插入。纯文本令牌无法恢复。 5. 部署边缘函数： ```bash supabase functions deploy memory --no-verify-jwt ``` 6. 使用纯文本客户端令牌调用 API： ```bash export MEMORY_API_URL="https://YOUR_PROJECT_REF.supabase.co/functions/v1/memory" export MEMORY_TOKEN="amf_..." curl -s "$MEMORY_API_URL" \ -H "authorization: Bearer $MEMORY_TOKEN" \ -H "content-type: application/json" \ -d '{"action":"remember","namespace":"platform","content":"使用 supabase functions deploy memory --no-verify-jwt 部署。","kind":"procedure","source":"README"}' curl -s "$MEMORY_API_URL" \ -H "authorization: Bearer $MEMORY_TOKEN" \ -H "content-type: application/json" \ -d '{"action":"recall","namespace":"platform","query":"如何部署内存函数？","limit":5}' ``` `MEMORY_TOKEN` 仍可以设置为边缘函数的机密用于引导或紧急管理。遗留令牌具有通配符访问权限，因此新安装应优先使用哈希作用域客户端，并将边缘 `MEMORY_TOKEN` 留空。 ## MCP 使用任何作用域令牌运行本地_stdio_适配器： ```bash MEMORY_API_URL="$MEMORY_API_URL" MEMORY_TOKEN="$MEMORY_TOKEN" npm run mcp ``` 始终在线的核心工具集是： - `memory_health` - `memory_whoami` - `memory_remember` - `memory_recall` - `memory_retire` - `memory_supersede` v1.2 还注册了上下文、批处理、事件、来源、关系、文档和维护工具。`memory_health` 是机器可读的能力源。 加密秘密工具在未显式设置 `MCP_ENABLE_SECRET_TOOLS=true` 和授予客户端匹配的秘密权限时不可用。参见 [docs/MCP.md](docs/MCP.md)。 _stdio_服务器遵循 MCP 指南，通过从其环境中读取凭证。任何外部服务都可以使用其自己的作用域令牌运行此适配器。v1.2 还提供了一个可选的无会话 HTTP MCP 边缘函数，受到 Supabase Auth OAuth 2.1 和显式数据库授予的保护。它从不暴露 Vault 工具。参见 [docs/REMOTE_MCP.md](docs/REMOTE_MCP.md)。 ## v1.2 模块化功能 调用 `health` 以发现协议、嵌入配置文件、操作和已安装的模块清单。所需的 `core` 保持较小；事件、来源、关系、文档、维护、Vault 机密和远程 MCP 是隔离的模块，它们重用相同的授权和 API。 ```bash # 安全、可重试的活动捕获 curl -s "$MEMORY_API_URL" \ -H "authorization: Bearer $MEMORY_TOKEN" \ -H "content-type: application/json" \ -d '{"protocol_version":"1","action":"event_append","namespace":"platform","event_type":"deploy.completed","summary":"生产部署完成，烟雾检查通过。","source_system":"deploy-agent","external_id":"deploy-2026-07-10"}' # 跨显式授予的命名空间的确定性上下文 curl -s "$MEMORY_API_URL" \ -H "authorization: Bearer $MEMORY_TOKEN" \ -H "content-type: application/json" \ -d '{"protocol_version":"1","action":"context","query":"最新部署中发生了什么变化？","namespaces":["platform","operations"],"max_chars":12000,"include_events":true}' ``` 便携式导出和本地文本文档摄入默认情况下是干燥运行/安全的或严格有界的。参见 [PORTABILITY.md](docs/PORTABILITY.md) 和 [DOCUMENTS.md](docs/DOCUMENTS.md)。 ## 验证 ```bash npm run check deno task check deno task test npm audit --omit=dev ``` 在播种部署特定的评估 ID 之后： ```bash MEMORY_EVAL_FIXTURES=eval/fixtures.local.json npm run eval ``` ## 仓库地图 - `AI.md` - 适用于任何 AI 编程代理的紧凑路由说明 - `INSTALL_WITH_AI.md` - 可复制粘贴的交接提示 - `docs/INDEX.md` - 完整文档导航 - `docs/AI_AGENT_INSTALL.md` - 代理部署/集成/验证合同 - `docs/MODULES.md` - 稳定的核心/模块缝隙和扩展规则 - `docs/PROTOCOL.md` - 协议 v1、能力发现和幂等性 - `docs/EVENTS.md` - 安全的代理活动日志 - `docs/PROVENANCE.md` - 新鲜度和证据关系 - `docs/DOCUMENTS.md` - 可选的文本文档摄入和搜索 - `docs/PORTABILITY.md` - 校验和导出/导入 - `docs/REMOTE_MCP.md` - 可选的 Supabase OAuth 2.1 远程 MCP - `docs/UPGRADE_V1_2.md` - 添加升级和回滚 - `docs/FAQ.md` - 所有权、成本、模型、安全性和集成答案 - `docs/AUDIT.md` - 完整仓库审计和补救记录 - `docs/ARCHITECTURE.md` - 系统形状和信任边界 - `docs/SECURITY.md` - 威胁模型、令牌范围和机密语义 - `docs/MCP.md` - MCP 工具和客户端配置 - `docs/OPERATIONS.md` - 部署、轮换、撤销、备份和恢复 - `docs/ZERO_COST_SSOT_MEMORY.md` - 规范实施指南 - `supabase/migrations/` - 添加数据库合同 - `supabase/functions/memory/` - 边缘函数和测试的纯帮助器 - `supabase/functions/mcp/` - 可选的 OAuth 保护的流式 HTTP MCP - `schemas/` - 机器可读的协议、模块和便携式合同 - `packages/client/` - TypeScript HTTPS 客户端 - `packages/mcp-server/` - stdio MCP 适配器 - `scripts/scaffold-integration.ts` - 干燥运行目标仓库集成 - `eval/` 和 `scripts/eval.ts` - 检索质量门控 ## 免费层边界 设计针对当前的 Supabase 免费计划：500 MB 数据库配额、免费边缘函数分配和项目暂停后低活动周。这些是供应商限制，而不是架构保证，因此在部署前请验证它们：[pricing](https://supabase.com/pricing)、[database size](https://supabase.com/docs/guides/platform/database-size) 和 [project pausing](https://supabase.com/docs/guides/platform/free-project-pausing)。 ## 非目标 - 没有内置的散文生成或模型特定的提示格式。 - 没有应用程序管理的加密密钥或自定义加密格式。 - 没有公共浏览器令牌、直接客户端访问 Postgres 或宽容的 RLS。 - 默认路径中没有付费 API 或托管 LLM 依赖。 - MCP 中没有第二个排名实现。 Postgres 中保留完整的原始内容。嵌入模型仅影响语义排名；全文检索、来源和导出保持可检查和提供者中立。 ## 开源和署名 Ai-Memory-Free 可以在 [MIT License](LICENSE) 下用于商业项目，无需付费或托管订阅。请在复制或实质性部分中保留许可证声明。 该项目由 [Kristian Peter](https://kristianpeter.com) 创建，他是一名首席自动化官，正在构建 AI 语音、营销和工作流系统，使一名操作员可以运行整个公司。感谢并欢迎贡献。参见 [CONTRIBUTING.md](CONTRIBUTING.md)、[SUPPORT.md](SUPPORT.md) 和 [SECURITY.md](SECURITY.md) 中的私人报告过程。