AI导哈

AI代理上下文管理服务

一个基于Cloudflare Worker的模型上下文协议(MCP)服务器，用于长期任务、记忆和上下文管理，为AI代理提供持久化、结构化的跨会话上下文。

  • by 23f2005217
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 23f2005217/mcp-todo

使用说明

一切

Cloudflare Worker暴露了一个 模型上下文协议（MCP） 用于长期任务、内存和上下文管理的服务器。它旨在为AI代理提供跨对话的持久、结构化的上下文，同时保持启动有效载荷的小和确定性。

  • 端点： https://mcp-todo.linuxgaruda52.workers.dev/mcp
  • 健康检查： GET / 返回服务器状态和当前应用程序设置。

它做什么

mcp-todo 是一个确定性的人工智能记忆系统。它将任务、记忆、项目、目标和关系存储在 第1天，将热上下文缓存在 千伏，并在中索引任务文本 向量化 用于语义搜索。工作人员公开了一小部分MCP工具，AI代理可以调用这些工具：

  • 使用标签、项目、组、优先级和生命周期状态捕获任务和记忆。
  • 确定性地查询和更改状态。
  • 检索每个新对话中的重点启动上下文。
  • 仅在需要时逐步加载主题摘要、项目上下文和原始记忆。
  • 在存储的项目之间进行语义搜索。
  • 发现并巩固重复或被取代的记忆。

设计原则： 数据库决定返回什么；人工智能只决定它接下来想知道什么。检索是确定性的。人工智能仅用于增强（语义搜索的嵌入、建议的关系、摘要）。

平台绑定

绑定 服务 目的
env.DB D1 用于待办事项、项目、标签、关系、事件、日志的关系存储。
env.APP_KV KV 缓存启动上下文、上下文摘要、应用程序设置和活动焦点。
env.TASK_VECTORS 矢量化 任务/内存文本的语义搜索索引。
env.AI Workers AI 为Vectorize生成嵌入(@cf/baai/bge-base-en-v1.5).

在中配置它们 wrangler.jsonc.

核心概念

上下文层次结构

检索按层次组织。只有当需要更多细节时，人工智能才应该在层次结构中向下移动：

Startup Context
    ↓
Topic Summary
    ↓
Project Context
    ↓
Raw Memories
  • 启动上下文 --极其轻量级：配置文件、活动目标、当前焦点、活动项目、始终加载项目和主题摘要。
  • 主题摘要 --主题/组的单个规范活动项加上确定性汇总。
  • 项目背景 --项目、活动目标、活动项目、重复系统和可选历史记录。
  • 原始记忆 --单个项目，按标签、组、项目、生命周期状态和启动优先级进行确定性过滤。

物品

中央桌子是 todos一个项目可以是：

  • item_kind: task 或 memory
  • entity_type: tactical_task, strategic_goal, recurring_system, context_memory, archived_history
  • lifecycle_state: active, dormant, stale, superseded, archived, completed
  • startup_priority: 0 （启动时切勿加载） 10 （始终加载）。仅限手动分配。

项目可以被固定、标记、分配给项目/组，并链接到目标。

上下文组

组是确定性检索桶。每个小组都有：

  • group_kind: topic, profile, project，或 system
  • retrieval_priority：控制该组是否包含在启动主题摘要中
  • canonical_item_id：表示主题当前状态的单个活动项

标签仍用于组织和搜索；组定义了确定性检索行为。

项目和目标

  • 项目 小组工作。
  • 目标 是 strategic_goal 链接到具有活动/已取代状态的项目的项。
  • 一个项目可以有一个 active_objective_id 代表当前的北极星。

关系

item_relationships 将项目与类型链接：

  • supersedes, replaces, derived_from --标记历史谱系
  • duplicate_of --完全重复
  • blocks, depends_on, supports --依赖性跟踪

这些电力历史感知检索和整合工作流程。

创业优先理念

优先级是手动分配的，从不计算：

优先级 含义
10 启动时始终加载
8 通常负载
5 特定主题
2 历史
0 启动时从不加载

MCP工具

应用程序设置

  • get_app_settings --读取全局默认值。
  • update_app_settings --更新默认值，如优先级、贪睡时间、接下来的几天。

捕获和管理项目

  • quick_add_task --使用默认值创建任务。
  • capture_context --快速捕获内存或上下文项。
  • get_item --按ID加载和丰富一个项目。
  • list_items --列出/过滤/分页项目。
  • update_item --更新标题、描述、状态、标签、项目等。
  • delete_item / delete_items --删除项目及其向量/关系。
  • set_item_startup_priority --控制启动时加载项目的速度。

项目和目标

  • create_project
  • get_project
  • list_projects
  • set_active_objective
  • get_project_timeline

状态转换

  • update_task_state --完成、暂停、忽略、重新激活、存档、取代。
  • supersede_items --将目标标记为已被源项取代。
  • mark_stale_candidates --查找旧的活动项目并将其标记为过时。

搜索

  • semantic_search --使用可选的种类过滤器对项目进行矢量搜索。
  • find_semantic_conflicts --查找与查询或项目类似的活动项目；返回重复/替换候选项。

上下文检索

  • load_context — 一个灵活的检索接口 对于整个层级结构。
    • level: "startup" --轻量级启动包。
    • level: "topic_summary" --一个主题的规范项目+确定性总结。
    • level: "project" --项目、目标、活动项、重复系统、可选历史记录。
    • level: "raw_memories" --过滤的原始项目（默认，向后兼容）。
  • get_startup_context --方便别名 load_context({ level: "startup" }).
  • get_context_summary --方便别名 load_context({ level: "topic_summary" }).
  • get_focus_context --当前的战略重点。
  • get_active_objectives, get_active_projects

整合工作流程

  • find_consolidation_candidates --对共享标签且可能是重复/超会话的记忆/任务进行确定性分组。
  • consolidate_memories --建立关系(duplicate_of, supersedes, replaces, derived_from)在守门员和目标物品之间，可以选择标记被取代的目标。

启动上下文(load_context / get_startup_context)

AI代理引导新对话的主要入口点。

启动上下文有意最小化。它回答：

  • 这个用户是谁？
  • 他们目前在做什么？
  • 他们的积极目标是什么？
  • 哪些项目正在进行中？
  • 什么话题很重要？

它确实如此。 不 加载每个固定内存。

退回的捆绑包

{
  "level": "startup",
  "source": "d1" | "kv_cache",
  "context_version": 123,
  "generated_at": "2026-07-01T...",
  "last_consolidated": "2026-07-01T...",
  "profile": { /* single current profile item */ },
  "active_goals": [ /* active strategic goals */ ],
  "current_focus": { /* project + objective + next tactical step */ },
  "active_projects": [ /* projects with active work */ ],
  "always_load": [ /* items with startup_priority = 10 */ ],
  "topic_summaries": [ /* canonical items for high-priority groups */ ]
}

该捆绑包缓存在KV下 context:startup 并在写入时无效。这 context_version 只有当底层项目发生变化时才会发生变化，因此AI代理可以在版本匹配时重用缓存的捆绑包。

主题摘要(load_context 随着 level: "topic_summary")

范围/主题的确定性汇总，缓存在KV下 context:summary:<scope>.

{
  "level": "topic_summary",
  "scope": "aws",
  "group": { "slug": "aws", "group_kind": "topic", "retrieval_priority": 8 },
  "canonical_item": { /* single current active representation */ },
  "summary": {
    "scope": "aws",
    "total": 12,
    "active_count": 5,
    "pinned_count": 2,
    "top_item": { "id": 42, "title": "Current AWS strategy" },
    "version": 7,
    "last_consolidated": "2026-07-01T...",
    "generated_at": "2026-07-01T..."
  },
  "source": "d1",
  "generated_at": "2026-07-01T..."
}

如果没有 canonical_item_id 如果在组上设置，则该组/标签中优先级最高的活动项将作为事实上的规范返回。使用 set_group_canonical_item 显式分配规范项。

项目背景(load_context 随着 level: "project")

加载项目、其活动目标、活动工时、重复系统和可选历史记录。

{
  "level": "project",
  "source": "d1",
  "project": { /* project record */ },
  "active_objective": { /* current strategic goal */ },
  "active_items": [ /* active project items */ ],
  "recurring_systems": [ /* recurring support items */ ],
  "history": [ /* superseded/archived/completed, only if include_history=true */ ],
  "generated_at": "2026-07-01T..."
}

确定性合并工作流程

  1. 呼叫 find_consolidation_candidates 获取共享标签的项目组。该工具是确定性的，使用现有的标签；语义搜索可以通过以下方式单独增强发现 find_semantic_conflicts.
  2. 审查建议的关系(duplicate_of, supersedes, replaces, derived_from)原因。
  3. 呼叫 consolidate_memories 带着一个 source_item_id （保管人）和 target_item_ids 创建关系，并可选择将目标标记为已取代。

不需要新的存储列；工作流重用现有的 item_relationships 表和生命周期状态。

项目结构

src/
  index.ts          # Worker fetch handler and MCP server setup
  tools.ts          # All MCP tool registrations
  db.ts             # Data model, queries, mutations, enrichment
  context.ts        # Context retrieval helpers and summary builder
  context-cache.ts  # KV cache helpers
  vectorize.ts      # Vectorize indexing and semantic search
  settings.ts       # App settings defaults and validation
  due.ts            # Due-date parsing
  context.test.ts   # Unit tests for context helpers
  tools.test.ts     # Unit tests for MCP tools
migrations/         # D1 schema migrations
wrangler.jsonc      # Cloudflare bindings and deploy config

发展

# Install dependencies
npm install

# Run TypeScript check
npx tsc --noEmit

# Compile tests
npx tsc -p tsconfig.test.json

# Run tests
node --test dist-test/src/context.test.js dist-test/src/tools.test.js

# Dry-run deploy
npm run deploy -- --dry-run

# Deploy
npm run deploy

本地开发人员

npx wrangler dev

MCP服务器可在 http://localhost:8787/mcp.

重要实施说明

  • D1是真理的来源。 Vectorize和KV是缓存/索引；那里的故障被捕获并且不会阻止D1写入。
  • 确定性检索： 数据库决定返回什么。排名使用显式元数据(startup_priority, retrieval_priority, lifecycle_state, pinned，最近）。检索中不涉及LLM。
  • 规范当前状态： 每个主题都可以有一个规范的活动项。旧版本仍通过以下方式存储 supersedes/replaces/derived_from 关系，但正常检索只返回活动版本。
  • 被取代/历史项目 仅在以下情况下返回 include_history=true.
  • 上下文无效： 写入清除活动焦点缓存，并酌情使启动/主题/项目缓存无效。
  • AI是可选的： 它只会增强组织（总结、嵌入、合并建议）；它从不控制正确性或检索顺序。

部署状态

上次部署时间： 2026-07-01 当前生产版本： 9d09fb45-ac34-49ff-9c12-3ac737497830

相关 MCP