ContextFirewall

<div align="center"> <img src=".github/assets/hero.svg" alt="ContextFirewall — guardrails for the memory layer" width="100%"> <br/> **适用于 AI 编程代理的信任防火墙。** 每个代理回忆、存储、提炼或遗忘的记忆都通过 [Cognee](https://github.com/topoteretes/cognee) 和四项防火墙检查——因此过时、矛盾、带有秘密和不支持的记忆永远不会到达模型。 <br/> [](https://github.com/topoteretes/cognee) [](https://modelcontextprotocol.io) [](backend) [](frontend) [](#evidence-real-runs-no-mocks) [](https://himanshukumarjha-contextfirewall.hf.space/health) **[◆ Live console](https://contextfirewall.vercel.app)** · **[⚡ MCP endpoint](https://himanshukumarjha-contextfirewall.hf.space/mcp)** · **[📖 API docs](https://himanshukumarjha-contextfirewall.hf.space/docs)** _{为 **WeMakeDevs × Cognee** 黑客马拉松而建 — *The Hangover Part AI: Where's My Context?* (Jun 29 – Jul 5, 2026)} <br/><br/> ### ▶ See it work — the four Cognee verbs, live <a href="https://github.com/himanshu748/ContextFirewall/raw/main/.github/assets/demo_sound.mp4"><img src=".github/assets/demo.gif" alt="ContextFirewall demo — remember, recall, improve, forget on the live console" width="90%"></a> _{▲ real console, real Cognee calls (Neo4j · Postgres · pgvector · Qwen2.5-72B) — no mocks · **[🔊 narrated walkthrough — 60s, with sound ↗](https://github.com/himanshu748/ContextFirewall/raw/main/.github/assets/demo_sound.mp4)** · [silent MP4 ↗](https://github.com/himanshu748/ContextFirewall/raw/main/.github/assets/demo.mp4) · [40s brand teaser ↗](https://github.com/himanshu748/ContextFirewall/raw/main/.github/assets/launch.mp4)} </div> --- ## 问题 AI 编程代理正在获得长期记忆。但是过时、矛盾、泄露或未经验证的记忆比没有记忆更糟糕——它会悄悄地引导下一个代理走向错误： - 一个在上周更改的被记住的 `deploy` 命令， - 一个后来被证明是错误的“修复”， - 在转录中捕获的 API 密钥， - 一个有证据支持的自信声明。 今天，所有这些都直接流入下一个会话的上下文中。**ContextFirewall 在重用每个被记住的事实之前进行审计，并为您提供忘记控制** - 通过一行代码降低到任何支持 MCP 的代理堆栈中。 <div align="center"> <img src=".github/assets/checks.svg" alt="The four firewall checks" width="100%"> </div> | 检查 | 内存被 **阻止** 时... | |------|------------------------------| | 🟡 **过时/有效性** | 更新的值取代它（部署目标更改） | | 🔴 **矛盾** | 更有支持的内存不同意（较弱的一方失败，获胜者通过） | | 🔵 **秘密/敏感性** | 它携带凭证 - 在 **ingest** 时编辑 **，因此它永远不会持续并且永远不会到达包 | | 🟢 **证据/信任** | 它不受支持：低信任分数，没有记录证据 | 只有通过 **所有四项** 检查的记忆才会被组装成一个 **受信任的上下文包**。未管理的原始回忆会在旁边显示，这样您就可以确切地看到防火墙阻止了什么。人类或代理可以通过 `forget_memory` 撤销任何记忆；它从 Cognee 中删除，这样它就永远不会重新出现。 --- ## 连接您的代理（MCP） ContextFirewall 是一个模型上下文协议服务器，具有 **两个传输和一个相同的六工具表面**，因此它可以适用于您使用的任何代理。 **Claude Code — 主机（单行，无需安装）：** ```bash claude mcp add --transport http contextfirewall https://himanshukumarjha-contextfirewall.hf.space/mcp ``` **Claude Code — 本地和私有（`uvx`，无需离开您的机器）：** ```bash claude mcp add contextfirewall \ --env CF_API_BASE=https://himanshukumarjha-contextfirewall.hf.space \ -- uvx --from "git+https://github.com/himanshu748/ContextFirewall#subdirectory=mcp" contextfirewall-mcp ``` **Cursor / Cline / generic (`~/.cursor/mcp.json` 或 `mcp.json`）：** ```json { "mcpServers": { "contextfirewall": { "url": "https://himanshukumarjha-contextfirewall.hf.space/mcp" } } } ``` **Windsurf (`~/.codeium/windsurf/mcp_config.json`）- 键是 `serverUrl`，不是 `url`：** ```json { "mcpServers": { "contextfirewall": { "serverUrl": "https://himanshukumarjha-contextfirewall.hf.space/mcp" } } } ``` ### 六种工具 | 工具 | Cognee 动词 | 它做什么 | |------|-------------|--------------| | `get_trusted_context(task)` | recall | 返回一个受信任的上下文包：只有通过所有四项检查的记忆。 | | `audit_context(task)` | recall | 每个内存的判决 - 批准，阻止，失败的检查以及原因，加上 `memory_id`。 | | `remember(text, subject, kind)` | remember | 存储一个持久的事实；下次回忆时可审计。秘密在 ingest 时被编辑。 | | `forget_memory(memory_id)` | forget | 从图 **和** 矢量存储中删除一个内存，以便它永远不会重新出现。 | | `improve_rules()` | improve / memify | 从记录的会话中提炼可重复使用的 `Rule` 节点。 | | `list_coding_rules(query)` | recall | 检索提炼的编码规则（`CODING_RULES` 搜索）。 | > **循环：** 在采取行动之前调用 `get_trusted_context`，在学习过程中记住持久的事实，完成后改进规则，并在需要时忘记记忆。 完整的客户端设置和隐私说明在 [`mcp/README.md`](mcp/README.md) 中。 --- ## 建立在 Cognee 的完整内存生命周期之上 <div align="center"> <img src=".github/assets/lifecycle.svg" alt="remember → recall → improve → forget" width="80%"> </div> ContextFirewall 使用 **所有四个** Cognee 动词，每个 MCP 工具都映射到一个。 | 动词 | ContextFirewall 如何使用它 | |------|------------------------------| | **记住** | `cognee.add` + `cognify` 从会话转录中构建实体图，加上一个 typed `Repo → AgentSession → SessionEvent → Memory` 图（带有 `supersedes` 关系），因此防火墙有确定的对象进行审计。`remember(...)` 是单次路径。 | | **回忆** | `cognee.search`（`GRAPH_COMPLETION`）用于无管理的基线，加上矢量回忆内存节点与它们的图属性连接，以收集防火墙审计的候选。 | | **改进** | `memify` 将持久的 `Rule` 节点提炼到 `coding_agent_rules` 节点集，可通过 `SearchType.CODING_RULES` 检索；信任分数源于证据和强化。 | | **忘记** | 治理：拒绝或阻止的内存从图和矢量存储中删除。 | 图是 **承载** 的：过时依赖于时间上的取代，矛盾在同一主题的回忆集群内被仲裁，受信任的包从类型节点组装 - 而不是一个扁平的矢量列表。 --- ## 隐私第一 隐私不是一个附加功能 - 它是数据路径的构建方式。 - 🔒 **秘密在摄入时被编辑，然后在每次读取时再次编辑。** 当会话被记住时，任何检测到的凭证（API 密钥，DB URI，私钥，AWS 密钥，JWT，`secret=…` 赋值，高熵令牌）都会在写入图，矢量存储或认知转录之前被剥离 **。** 它永远不会持续 - 防火墙仍然会阻止它来自的内存。每个读取路径（`/audit`，`/pack`，`/graph`，回忆）在第二层防御深度中再次编辑。 - 🧭 **默认情况下本地化。** 在开发中，Cognee 的存储是本地文件（SQLite + LanceDB + 默认图）；默认情况下，模型和嵌入仍然调用 Hugging Face 路由器，但指向本地 OpenAI 兼容的端点（参见下面的本地模型选项），并且没有任何内容离开机器。托管的 Neo4j Aura + Supabase pgvector 仅用于托管演示；自我托管和您的内存图保留您自己的。 - 🧩 **每个帐户的命名空间隔离。** 经过身份验证的调用者的 API 密钥解析为私有命名空间；读取仅限于 **该命名空间** - 您的控制台永远不会混入公共样本数据。Supabase RLS 锁定底层表。 - 💻 **本地模型选项。** 模型和嵌入端点可通过环境变量配置 - 将它们指向本地 OpenAI 兼容的服务器（例如 Ollama）以实现完全离线部署。 在 [`backend/app/firewall/secrets.py`](backend/app/firewall/secrets.py) 中查看检测器，在 [`backend/app/identity.py`](backend/app/identity.py) 中查看命名空间解析。 --- ## 架构 ``` Claude Code · Cursor · Windsurf · Cline · 任意 MCP 客户端 │ ▼ ┌──────────────────────────────────────────────────────────────┐ │ MCP 服务器 /mcp （流式 HTTP，无状态） │ │ REST API /pack /audit /remember /forget ... │ ├──────────────────────────────────────────────────────────────┤ │ 一个防火墙核心 → 4 检查 → 受信任的包 │ ├──────────────────────────────────────────────────────────────┤ │ Cognee = 图 + 矢量 + 关系存储 │ └──────────────────────────────────────────────────────────────┘ ▲ │ 实时控制台（Next.js / Vercel） ──────────────┘ 开发： SQLite · LanceDB · Kuzu 图 │ 生产： Neo4j Aura · Supabase pgvector ``` - **MCP 服务器** - 标头表面，安装在 `/mcp`（流式 HTTP，无状态），以及 [`mcp/`](mcp) 下的零依赖 `uvx` stdio 包用于笔记本电脑。两者都从一个定义暴露相同的六种工具。 - **后端** - FastAPI + Cognee SDK（Python 3.12），部署为 Docker **Hugging Face Space**。MCP 工具和 REST 端点调用 **一个** 防火墙/Cognee 核心 - 没有重复的逻辑。 - **模型层** - Hugging Face 推理路由器：**Qwen2.5-72B-Instruct** 用于图提取和矛盾仲裁，**BAAI/bge-small-en-v1.5** 嵌入（384-dim）。 - **存储** - 在 `bootstrap.py` 中通过环境变量切换：开发中的本地存储，生产中的 Supabase Postgres + pgvector 和 Neo4j Aura。相同的代码。 - **前端** - Next.js + Tailwind 在 **Vercel** 上：交互式强制有向知识图，连接视图，会话重放和实时防火墙活动馈送。 ### API MCP 工具是主要界面；这些 REST 端点支持它们并为控制台提供支持。 | 方法 | 路径 | 目的 | |--------|------|---------| | `ANY` | `/mcp` | **MCP 服务器（流式 HTTP）：六个防火墙工具** | | `GET` | `/health` | 实时配置文件（提供者，模型）+ 节点计数 | | `POST` | `/pack` | 受信任的上下文包（和无管理的基线） | | `POST` | `/audit` | 回忆 + 运行四项检查，每个内存的判决 | | `POST` | `/remember` · `/ingest` | 记住一个事实 / 记录的会话 | | `POST` | `/improve` · `GET /rules` | 提炼编码规则（memify）/ 回忆它们 | | `POST` | `/forget` | 从 Cognee 中删除内存（治理） | | `GET` | `/graph` · `/activity` | 知识图节点+边 / 实时防火墙馈送 | | `GET` | `/sessions/{id}/timeline` | 会话重放 | | `POST` | `/demo/seed` | 消化捆绑的样本会话（幂等） | 尝试在实时 API 上使用受信任的包： ```bash curl -s -X POST https://himanshukumarjha-contextfirewall.hf.space/pack \ -H 'content-type: application/json' \ -d '{"query": "How do I deploy taskflow-api safely?"}' ``` --- ## 本地运行 ```bash # 后端 cd backend uv venv --python 3.12 .venv && uv pip install -r requirements.txt cp .env.example .env # 添加您的 Hugging Face API 密钥 set -a && . ./.env && set +a PYTHONPATH=. .venv/bin/python scripts/dev_integration.py # 在真实的 Cognee 上进行端到端检查 PYTHONPATH=. .venv/bin/uvicorn app.main:app --port 8000 # MCP 在 /mcp，API 在 / # 前端 cd frontend npm install echo "NEXT_PUBLIC_API_URL=http://localhost:8000" > .env.local npm run dev ``` 对于本地开发，您只需要一个 Hugging Face API 密钥；Cognee 使用本地文件存储。设置 Postgres/pgvector/Neo4j 变量，相同的代码将外部存储。 --- ## 演示数据 - 什么是真实的 捆绑的演示是 **一个虚拟的 `taskflow-api` 存储库** （FastAPI，Postgres，Redis，Stripe）上的 **示例代理会话**。代理商入职并获得一个搜索延迟票。十个记忆是清晰的 **输入**，设计用于锻炼每个检查： - **过时** - `flyctl deploy --remote-only`（2 月）被 `make release`（6 月）取代。 - **矛盾** - “JWT 访问令牌永远不会过期”（信任 0.45）输给“过期 15 分钟，使用刷新流程”（已验证）。 - **秘密** - 工作配置注释中的 AWS 访问密钥被检测并编辑（`AKIA…PLE`）。 - **证据** - `/search` 维持 1,000,000 req/s，无缓存（信任 0.10）并被阻止。 **所有 ** 下游输入都是系统输出：** 判决、信任分数、知识图、提炼的规则和受信任的包都来自实时 Cognee 和实时模型。没有判决是硬编码的，结果也没有被编造。 ### 证据（真实运行，无模拟） - 完整的 MCP 动词循环在 **两个** 传输通道上针对真实 Cognee + Hugging Face 进行验证：`get_trusted_context` / `audit_context` 返回 **6 个批准和 4 个阻止**，原因恰好正确；`remember` 添加可审计的内存；`improve_rules` 提炼真实的 `Rule` 节点；`forget_memory` 从图和向量中删除。 - `scripts/mcp_http_probe.py` 和 `scripts/mcp_full_probe.py` 锻炼托管端点；`mcp/tests/test_mcp.py` 涵盖_stdio 路径和协议握手。 - `cognify` 在 Qwen2.5-72B 上实时运行；`GRAPH_COMPLETION` 正确推理时间部署命令更改。 - **35 个单元测试通过**（`tests/test_secrets.py`，`test_checks.py`，`test_identity.py`，`test_namespace.py`）。 - 生产运行在托管存储：`/health` 报告 `graph: neo4j`，`relational: postgres`，`vector: pgvector`。 --- ## 路线图 - **信任随时间重新加权** - 加强证明正确的记忆，衰减那些不正确的记忆。 - **连续自动记录** 实时代理会话，而不是显式 `remember` 调用。 - **跨会话累积内存**，防火墙管理增长的图。 - **托管 Cognee Cloud** 作为托管选项。 --- <div align="center" _{使用 AI 助手（**Hyperagent**）构建，按黑客马拉松规则公开。所有 Cognee 用法都是真实的 - 实时模型和图调用，不是模拟。演示会话是一个清晰标记的示例；每个防火墙判决显示为真实系统输出。} <br/> **[◆ 打开控制台](https://contextfirewall.vercel.app)** · **[⚡ 通过 MCP 连接](https://himanshukumarjha-contextfirewall.hf.space/mcp)** · **[🛡️ 源代码](https://github.com/himanshu748/ContextFirewall)**</div>