Context Helper

ContextHelper

ContextHelper 是用于长时间运行的代理和IDE的共享内存基础架构层。

它建立在一个简单的信念之上： 当内存被视为一级系统时，代理的故障更少，而不是巨大提示的意外副作用.

ContextHelper将完成的聊天历史记录转换为 可观察、可控、可重用和共享内存系统。它构建结构化内存包，将最新讨论保留为 活尾，运行后台维护，并通过MCP和HTTP公开该内存，以便多个代理和应用程序可以使用相同的上下文层。

为什么这个项目很重要

长时间运行的编码会话是代理开始崩溃的地方：

• 重要决定消失在老聊天中
• 过时的假设又回来了，就像它们仍然是真的一样
• 代理人无法跟踪所做的事情、有风险的事情以及仍然需要注意的事情

ContextHelper正试图直接解决这个问题。

目标不是“只是另一个MCP服务器”。目标是使 代理内存实用、可检查且可在实际开发工作流程中移植 当聊天时间很长时，任务会发生变化，上下文漂移会成为隐藏的失败模式。

内存作为基础架构

大多数代理产品已经有某种形式的内置摘要。这不是真正的区别。

ContextHelper针对的是不同的层：

• 可观察对象：记忆可以被检查、评分、区分、审核，并追溯到成绩单/源材料
• 可控的：客户端可以有意识地摄取、重新汇总、清理、查询和维护内存
• 可重复使用的：内存在一个聊天窗口后仍然存在，可以在会话之间恢复
• 共享：多个代理和应用程序可以从同一个工作区内存层读取，而不是每个都保留一个私有的黑盒摘要

这才是真正的卖点： 将代理内存转化为基础架构，而不是将其困在一个聊天UI中.

项目状态

ContextHelper仍然 早期.

基础在这里：

• 本地MCP服务器 stdio
• SQLite支持的转录、快照和摘要作业存储
• 滚动汇总模型 summary + liveTail
• 从以下位置自动摄取Kiro会话存储 ~/.kiro/sessions
• 具有重试和死信处理功能的持久摘要作业队列
• 摘要质量评分和快照差异生成
• 通过目标后端查询进行选择性内存召回
• 后端内存管理员，用于修剪嘈杂的数据包和清理过时的对话
• 后端内存代理，用于分析过度汇总、实时尾部、差异和质量信号
• 文档URL和GitHub存储库的工作区范围外部知识同步
• 基于新鲜度感知背景同步的同步web/repo文档的外部知识查询
• 结构化运行时日志记录和工作人员健康检查
• 基于代理的回退局部启发式摘要
• 测试了自动摘要、滚动覆盖和引导路径的核心行为

它仍然需要通过实际使用来强化生产：更好的IDE适配器、更强的会话身份处理以及来自长时间运行的编码工作流的更多数据。

需要帮助

如果这个问题对你很重要，欢迎捐款。

帮助将立即产生影响的领域：

• 更好的对话和线程身份处理
• 更强的重试和提供程序回退行为
• 更智能的摘要更新策略和评估
• 支持更多IDE和代理客户端
• 长时间实施会话的真实世界测试

这是架构真实存在的阶段，但项目仍然可以朝着正确的方向发展。如果你想帮助为编码代理构建一个严肃的内存层，现在是加入的好时机。

ContextHelper做什么

ContextHelper为代理提供了两层内存：

• 长期记忆 通过结构化摘要包
• 短期记忆 通过最新回合的实时追踪

这意味着：

• 成绩单是真相的来源
• 稳定的历史被压缩到持久的上下文中
• 新的讨论保持新鲜和未压缩的时间足够长，以保持准确性

运作原理

flowchart LR
    subgraph Providers["Providers / Agent Apps"]
        Kiro["Kiro Sessions"]
        Codex["Codex Sessions"]
        Other["Other MCP or HTTP Clients"]
    end

    subgraph Ingestion["Ingestion Layer"]
        KiroAdapter["Kiro Adapter"]
        CodexAdapter["Codex Adapter"]
        MCPHTTP["MCP Tools / HTTP API"]
    end

    subgraph MemoryCore["ContextHelper Memory Core"]
        Transcript["Raw Transcript Store
SQLite"]
        Queue["Summary Job Queue"]
        Summarizer["Rolling Summarizer"]
        Reconcile["Workspace Reconciliation"]
        Janitor["Janitor + Autopilot"]
        External["External Knowledge Sync"]
    end

    subgraph Outputs["Context Outputs"]
        Conv["Conversation Context
summary + liveTail"]
        Resume["Workspace Resume Context"]
        Agent["Memory Agent / Orchestrator"]
        Shared["Shared Memory for Multiple Agents"]
    end

    Kiro --> KiroAdapter --> Transcript
    Codex --> CodexAdapter --> Transcript
    Other --> MCPHTTP --> Transcript

    Transcript --> Queue --> Summarizer --> Conv
    Transcript --> Reconcile --> Resume
    Summarizer --> Reconcile
    Transcript --> Janitor
    External --> Agent
    Conv --> Agent
    Resume --> Agent
    Agent --> Shared

在实践中，流程是：

1. 提供商推送已完成的转弯，或内置适配器自动同步它们
2. ContextHelper将原始转录存储在SQLite中
3. 旧的稳定上下文被总结为结构化内存，而最新的上下文则保持不变 liveTail
4. 来自同一工作区中多个会话和提供者的内存被协调到一个更干净的共享视图中
5. 代理读取对话记忆、工作区恢复记忆或编排好的答案，而不是重放原始聊天历史记录

核心理念

内存模型故意简单：

1. 完成的回合被推送到ContextHelper中
2. 原始转录本存储在SQLite中
3. 旧的稳定转弯被折叠成摘要包
4. 最新的转折点还在 liveTail
5. 代理从两层恢复状态，而不是重放整个聊天

这使得代理可以继续移动，而不会携带臃肿且越来越不可靠的对话历史。

特别是对于Kiro和Codex，ContextHelper可以直接从本地会话存储同步，因此转录摄取不再依赖于指导文件或代理记住调用摄取工具。

外部知识

ContextHelper现在还承载了旧版本的轻量级子集 context8 想法： 每个工作空间都有新鲜的外部知识.

这意味着工作区可以注册以下源：

• 官方文档URL
• GitHub 仓库
• markdown文档集合

ContextHelper可以：

• 获取最新内容
• 将其与对话记忆一起存储在SQLite中
• 按新鲜度间隔重新同步
• 根据同步的知识回答有针对性的问题

这为编码代理提供了第二条上下文通道：

• conversation memory 关于代理会话中发生的事情
• external knowledge 对于外部文档或repo文档目前所说的内容

IDE和提供商支持

Kiro是第一个内置的自动同步适配器，但ContextHelper并不局限于Kiro。

当前支持拆分如下：

• built-in auto-sync：Kiro和Codex会议商店
• generic MCP integration：任何可以调用MCP工具的IDE或代理
• generic HTTP integration：任何可以调用本地后端服务器的应用程序

因此，对于非Kiro提供商来说，流已经存在：

• 推动完成的转弯 ingest_conversation_turns
• 或致电 POST /api/v1/conversations/ingest
• 然后通过MCP或HTTP读回内存

今天仍然特定于提供者的只是自动本地会话摄取层。

这很重要，因为该项目并没有试图成为“更好的Kiro总结”。它正试图成为 共享内存后端 Codex、Kiro和其他代理客户都可以插入。

运行时模型

ContextHelper现在表现得像一个小型生产服务，而不是一个单一的内存循环：

• 对话回合会立即写入SQLite
• 符合条件的摘要作为持久作业排队
• 工人声称工作，重试暂时的失败，死信耗尽工作
• MCP客户端可以通过以下方式检查队列和循环运行状况 get_runtime_status
• 结构化日志被发送到 stderr，这使得MCP stdout 清洁

这种布局是有意紧凑的，但它为项目提供了一条通往真正部署的道路，而不是停留在快速的实验阶段。

部署模式

ContextHelper现在有三种运行时模式：

• npm start：MCP stdio 服务器
• npm run worker：独立后台工作者
• npm run http：独立的本地HTTP后端

HTTP后端绑定到 127.0.0.1:4321 默认情况下，允许非MCP应用程序直接使用ContextHelper。

有用的HTTP路由：

• GET /health
• GET /api/v1/runtime-status
• POST /api/v1/conversations/ingest
• POST /api/v1/conversations/context
• POST /api/v1/conversations/force-summarize
• POST /api/v1/workspace-memory/context
• POST /api/v1/workspace-memory/query
• POST /api/v1/external-sources/register
• GET /api/v1/external-sources
• POST /api/v1/external-sources/sync
• POST /api/v1/external-knowledge/query

MCP表面

工具

资源

示例上下文数据包

{
  "conversationSummary": "The project is building an MCP helper that prevents long-running IDE agents from drifting away from confirmed decisions.",
  "confirmedFacts": [
    "Kiro is the first target integration.",
    "Conversation history is stored in SQLite."
  ],
  "technicalDecisions": [
    "Use a structured context packet for long-term memory.",
    "Keep a live tail for the newest turns."
  ],
  "openTodos": [
    "Wire the Kiro-side adapter that pushes completed turns."
  ],
  "activeRisksOrUnknowns": [
    "Proxy routing or empty model responses can degrade summaries."
  ],
  "recentRelevantTurns": [
    "User asked to preserve fresh context while compressing older stable discussion."
  ]
}

滚动记忆模型

ContextHelper可以 不 总是总结一切。

它使用滚动策略：

• 只有在最后一个回合完成助理回合后才能进行总结
• 等待一个空闲的去抖动窗口
• 保持最新 SUMMARY_LIVE_TAIL_TURNS 超越长期记忆
• 只将旧的马厩折成摘要包

这是项目背后的核心设计选择： 记忆应该保持紧凑，而不会使活跃的对话变得平淡.

记忆智能

ContextHelper现在在原始摘要存储之上添加了一个精简的后端智能层：

• 每个快照都可以对摘要质量进行评分
• 每次刷新都会产生与前一个快照的结构化差异
• 客户端可以有选择地查询内存，而不是每次都加载完整的数据包
• 清洁工会在包裹被保存之前对其进行消毒和修剪
• 维护人员可以从SQLite中删除过时或多余的对话
• 后端内存代理可以将摘要、差异、质量和实时尾部综合在一起
• 自动驾驶回路可以审计最近的对话并安排维护行动，而无需等待客户端的询问

这很重要，因为长时间运行的代理通常不需要 *全部* 每一个转弯都有记忆。在许多情况下，他们只需要与一个狭窄问题相关的决定、风险或未决工作。

自主记忆代理

ContextHelper现在有两种内存代理模式：

• consult_memory_agent 用于显式按需推理
• memory agent autopilot 用于背景审计

自动驾驶循环定期扫描最近的对话，过滤掉那些看起来过时或弱的对话，向后端内存代理查询一个小的有界集合，然后应用安全操作：

• 当内存过时时，排队或触发摘要刷新
• 需要保留工作时，要求清洁工清理
• 标记仍需重新检查的实时尾部密集对话

重要的设计选择是自动驾驶仪 不 尽量同步解决所有问题。在常见情况下，它为现有的摘要工作器安排工作，而不是阻止整个MCP工具调用。

混合上下文模型

ContextHelper现在更接近于混合内存系统：

• conversation memory：摘要、活尾、差异、质量、看门人、记忆代理
• workspace memory：合并最近对话中的内存
• external knowledge：从聊天室外部同步文档和存储库

这很重要，因为长时间运行的编码代理通常需要两者：

• 团队或代理人已经决定了什么
• 上游文档或仓库目前说什么

快速开始

npm install
npm run build
npm test
npm run kiro:sync
npm start
npm run http

MCP服务器运行 stdio，适用于Kiro等本地MCP客户端。

对于专门的后台工作流程：

npm run worker
npm run http

当地健康检查：

npm run smoke
npm run worker:once

配置

ContextHelper自动加载 .env 和 .env.local 从项目根开始。

核心设置

Worker和队列设置

LLM代理设置

如果缺少代理设置，ContextHelper将回退到确定性本地启发式摘要器，以便服务器仍能运行。

外部知识设置

HTTP服务器设置

内存监视器设置

内存代理自动驾驶设置

发展

npm run build
npm test
npm run kiro:sync
npm run smoke
npm run worker:once
npm run http

当前测试包括：

• 完成辅助转弯加怠速去抖动后的自动摘要
• 当最新回合仍然是用户回合时，没有自动摘要
• 滚动汇总行为，使活动尾部不在长期汇总范围内
• 跨多个对话的工作区内存合并
• 外部知识同步与查询行为
• 后端内存代理咨询，提供证据和建议
• 自主内存代理审计和动作调度
• 选择性记忆回忆与摘要差异生成
• 清洁工的卫生和滞留清理行为
• 队列支持的后台执行和干净的运行时引导路径
• Kiro会话存储摄取，具有稳定的基于光标的重复数据消除功能

项目结构

src/
  app.ts         MCP tool and resource registration
  config.ts      env loading and runtime config
  http.ts        local HTTP backend entrypoint
  index.ts       stdio server entrypoint
  worker.ts      dedicated background worker entrypoint
  service.ts     rolling summary orchestration and queueing
  storage.ts     SQLite persistence and coverage logic
  summarizer.ts  proxy adapter and fallback summarizer
  external/      external source fetch, sync, and query
  integrations/  Kiro session-store sync
  jobs/          summary job worker and retry flow
  llm/           OpenAI-compatible proxy client
  memory/        scoring, diffing, memory agent, janitor
  ops/           structured logging
  runtime/       process and scheduler primitives
  types.ts       shared domain types

路线图

• 更强大的提供程序回退和重试策略
• 更丰富的对话身份和会话生命周期支持
• 支持更多IDE代理
• 更好地评估现实世界中长时间运行的聊天

许可证

麻省理工学院