Forkscout Memory MCP

forkspect内存mcp

AI代理的持久长期记忆 --单机 主控程序 服务器为LLM提供了他们根本缺乏的东西：在对话中记忆、学习和发展的能力。

为 叉子侦察机 自主代理。适用于任何兼容MCP的客户端（VS Code Copilot、Claude Desktop、Cursor、自定义代理）。

______________________________________________________________________

问题：LLMs没有记忆

每次你与法学硕士开始对话，都是从零开始的。它不知道：

• 你昨天说了什么
• 你在做什么项目
• 它以前犯过什么错误，是如何纠正的
• 你是谁或你喜欢什么
• 已经做出了哪些决定，为什么

标准的“解决方案”实际上并没有解决这个问题：

核心问题： 这些系统都没有以智能实际工作的方式对知识进行建模。 它们存储数据。他们不坚持信仰。

______________________________________________________________________

此服务器的不同之处

forkspect内存mcp是一个 信念维持系统 伪装成MCP服务器。它为LLMs提供了：

1.有信心的结构化事实（不仅仅是字符串）

每个事实都有一个置信度得分、源计数和时间元数据：

"TypeScript is the primary language" → confidence: 0.92, sources: 5, last confirmed: 2h ago
"Port is 3211"                      → confidence: 0.85, sources: 2, last confirmed: 3d ago
"Uses webpack for bundling"         → confidence: 0.31, sources: 1, last confirmed: 90d ago ← stale

置信度是根据证据强度+新近度自动计算的。多个来源证实的事实排名更高。旧的未经证实的事实会衰减，但永远不会低于其证据下限（一次陈述的事实即使在一年后仍然得分0.30）。

为什么这很重要： 当LLM检索内存时，它会得到一个关于它最有信心的内容的排名视图，而不是一个关于所有记录内容的简单列表。

2.非破坏性信仰修正（取代，而非删除）

当新信息与旧信息相矛盾时，旧事实不会被删除，而是 取代:

✓ Active:     "Project uses AI SDK v6"  (confidence: 0.95)
  ⤷ Superseded: "Project uses AI SDK v5" → replaced by "Project uses AI SDK v6" (2025-12-15)
    ⤷ Superseded: "Project uses AI SDK v4" → replaced by "Project uses AI SDK v5" (2025-09-01)

完整的更正历史被保留。LLM可以检查 其信仰是如何演变的 --它过去犯了哪些错误，什么时候纠正了这些错误。

为什么这很重要： RAG和向量DB将过时的块永远与正确的块放在一起。LLM无法知道哪个版本是最新的。在这里，只有主动的事实出现在搜索中，但学习历史总是按需提供的。

3.自动矛盾检测

当“port is 3211”已存在时添加“port is 8080”会触发警告：

⚠️ CONTRADICTIONS DETECTED:
  • "port is 3211" vs "port is 8080" — Number/version conflict

三种检测策略：

• 否定模式 --“使用X”vs“不使用X”
• 数量/版本冲突 --相同的背景，不同的价值观
• 主题重叠分歧 --单词重叠程度高，但关键词不同（Jaccard相似性）

矛盾的事实会自动被取代。LLM受到警告，因此可以对冲突进行推理。

4.混合语义+BM25搜索

召回用途 并行运行的两个搜索层:

• BM25（词汇） --精确的关键字匹配，词频，快速
• 语义（向量） --基于意义的匹配 Xenova/all-MiniLM-L6-v2 （384-dim，量化ONNX，本地运行，不需要API密钥）

结果与可调的alpha权重合并（默认值：60%语义，40%BM25）。这意味着：

• 搜索“数据库端口”还可以找到“3211侦听地址”（语义）
• 搜索“libsimdjson”即使没有语义邻居，也能找到完全匹配的结果（BM25）
• 这两个信号在常见查询中相互强化

嵌入按需计算并缓存在 memory-embeddings.jsonXenova型号在首次启动时自动下载（约23MB）并保存到 TRANSFORMERS_CACHE （默认值： /data/.cache 在Docker中）。

5.跨项目隔离的多维标记

跨项目共享内存的首要问题： 搜索返回来自无关项目的噪声。

每个实体和交易所都可以被标记：

{
  "tags": {
    "project": "forkscout",
    "scope": "universal",
    "category": "debugging"
  }
}

搜索用途 智能过滤:

• 搜索方式 project: "forkscout" 返回：

- ✅ 已标记的项目 project: "forkscout" （项目特定） - ✅ 已标记的项目 scope: "universal" （跨项目知识） - ✅ 没有标签的项目（向后兼容，旧数据） - ❌ 已标记的项目 project: "other-project" （已过滤掉）

为什么这很重要： 周一在forkscot上工作、周二在future gain上工作的代理需要其TypeScript调试模式（通用），但不需要futuregain的数据库模式（特定于项目）。标签过滤器会自动执行此操作，而不需要LLM手动过滤结果。

6.具有120多种关系类型的知识图（非平面存储）

实体通过类型化的加权关系连接：

forkscout-memory-mcp  ──uses──▶  TypeScript       (weight: 0.95, 5x confirmed)
forkscout-memory-mcp  ──uses──▶  Bun              (weight: 0.80, 3x confirmed)
forkscout-memory-mcp  ──part-of──▶  Forkscout     (weight: 0.90, 4x confirmed)

跨越认知的30种实体类型(goal, task, plan, hypothesis, decision)，经验(event, outcome, failure, success)，以及环境(resource, state, signal).

120多种关系类型，分为15个类别，包括结构、故意、因果、时间和学习维度。反复的证据强化了这种关系——一个联系被独立陈述的次数越多，它的权重就越高。

7.自我认同和学习

代理维护一个自我实体，在那里记录对其自身行为的观察：

Forkscout Agent (agent-self):
  • [95%] Prefer spawn_agents for parallel research tasks
  • [88%] Always check memory before starting work
  • [72%] When debugging, reproduce the error first before reading code

这些自我观察在各个会话中积累。代理从字面上学习如何成为一个更好的代理——什么调试策略有效，用户喜欢什么通信模式，要避免什么错误。

8.具有自动重要性的交换内存+重复数据删除

对话交换被存储和搜索：

observe("How do I fix port conflict?", "Check if port 3211 is in use with lsof -i :3211...")
→ importance auto-calculated from message length + keyword density
→ deduplication: similar exchanges (>0.85 similarity) are merged, not duplicated
→ hot tier: last 500 exchanges in full
→ archive tier: older exchanges indexed by embedding only

交换可以按项目标记，以便进行范围召回。在搜索中，词汇和语义匹配都与交换历史相冲突。

9.工作记忆持久性（会话上下文）

会话中的工作内存（最近的操作、决策、错误）在服务器重启时持续存在：

"workingMemorySessions": {
  "session_abc": [
    { "content": "Started migrating schema to v7", "event_type": "action", "timestamp": 1708600000000 },
    { "content": "Found contradiction in port facts", "event_type": "observation" }
  ]
}

每个会话的最后25个事件将被保留。重新启动时，代理可以准确地回忆起它在任务中途停止的地方。

10.主动任务跟踪（执行记忆）

服务器重启后任务仍然存在：

⚡ Running: "Implement multi-dimensional tagging" (task_abc123) — 45min, P80
✓ Completed: "Fix planner duplicate processing" — 12min
✗ Aborted: "Migrate to Rust" — Deprioritized

2小时后自动过期可防止僵尸任务。类似任务检测可防止重复。

______________________________________________________________________

架构比较

┌─────────────────────────────────────────────────────────┐
│                   Traditional RAG                        │
│                                                         │
│  Documents → Chunker → Embeddings → Vector DB → Search  │
│                                                         │
│  ✗ No confidence       ✗ No contradiction handling      │
│  ✗ No belief evolution  ✗ No project scoping            │
│  ✗ Stale = Fresh        ✗ No relationships              │
└─────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────┐
│              forkscout-memory-mcp                        │
│                                                         │
│  Facts → Confidence + Sources → Contradiction Check →   │
│  Knowledge Graph (entities + relations) →               │
│  Tag-filtered Hybrid Search (BM25 + Semantic) →         │
│  Ranked results (confidence × recency × access) →       │
│  Supersession chains (belief evolution history)         │
│                                                         │
│  ✓ Confidence scoring   ✓ Automatic contradiction       │
│  ✓ Non-destructive      ✓ Multi-project isolation       │
│  ✓ Self-identity        ✓ Task tracking                 │
│  ✓ Relationship graph   ✓ Two-tier consolidation        │
│  ✓ Hybrid search        ✓ Working memory persistence    │
│  ✓ Exchange memory      ✓ Interactive visualizer        │
└─────────────────────────────────────────────────────────┘

______________________________________________________________________

快速开始

本地开发

bun install
bun --watch src/server.ts    # watch mode, auto-reload on changes

注： Bun是必需的。Xenova/all-MiniLM-L6-v2型号（约23MB）在首次启动时自动下载到 TRANSFORMERS_CACHE。后续启动是即时的。

生产

bun run src/server.ts        # Bun runs TypeScript natively — no build step

码头工人

docker build -t forkscout-memory-mcp .
docker run -d -p 3211:3211 -v memory-data:/data forkscout-memory-mcp

# or with docker compose
docker compose up -d

Docker中心/GHCR

docker pull ghcr.io/martianacademy/forkscout-memory-mcp:latest
docker run -d -p 3211:3211 -v memory-data:/data ghcr.io/martianacademy/forkscout-memory-mcp

从VS代码连接

添加 .vscode/mcp.json:

{
  "servers": {
    "forkscout-memory": {
      "type": "http",
      "url": "http://localhost:3211/mcp"
    }
  }
}

______________________________________________________________________

环境变量

______________________________________________________________________

端点

______________________________________________________________________

MCP工具（9）

remember --存储或更新实体事实

将事实存储在命名实体上。新的事实被合并了。矛盾会引发警告，并自动取代旧事实。

{
  "name": "forkscout-memory-mcp",
  "type": "service",
  "facts": ["HTTP port is 3211", "runs on Bun 1.3.9"],
  "tags": { "project": "forkscout" }
}

______________________________________________________________________

recall --多模态内存检索

五种检索模式覆盖所有存储层。

模式：

• search --BM25+跨实体+交换的语义混合搜索
• entity --按确切名称获取一个实体； include_history: true 显示替代链
• history --信仰演变：什么时候被纠正（要求 name)
• relations --所有知识图边；可选的 name 限制为一个实体
• exchanges --按关键字搜索对话历史记录

______________________________________________________________________

observe --录制对话交流

将一段重要的对话记录到长期记忆中，并推送到工作记忆中。

如果省略，重要性将根据消息长度和关键字密度自动计算。重复数据删除以0.85的相似性阈值运行——重复数据被合并，而不是附加。

只记录与非琐碎决策、根本原因或获得的见解的交流。跳过常规工具输出。

______________________________________________________________________

relate --建立或加强关系

在两个实体之间创建键入边。

重复边会自动合并并获得置信度权重。缺失的实体会自动创建为类型 other.

规则： 跑 recall(mode="search") 首先确认这两个名称的存在，避免创建重复的实体。

______________________________________________________________________

context --工作内存（会话范围）

在RAM中，会话范围的工作内存。跟踪你现在正在做什么：采取的行动、做出的决定、出现的错误。

保留每个会话的最后25个事件。会话开始时呼叫 action: "get" 回忆起你从哪里停下来的。工作记忆会持续到 memory.json 跨服务器重启。

______________________________________________________________________

task --用于多步工作的执行记忆

任务在服务器重启后仍然存在，并提供按时间顺序的跟踪。

• start：检测类似的现有任务以避免重复。退货 taskId.
• done：标记完成+自动保存成功记录以备将来召回。
• abort：停止+保存失败的事后分析，以备将来学习。
• list：显示所有具有已用持续时间的活动和暂停任务。

2小时后自动过期可防止僵尸任务。

______________________________________________________________________

introspect --内存自检

获取统计数据并识别过时或不稳定的事实。在会话启动时运行。

意见：

• stats --实体/关系/交换计数和类型细分
• stale --最近未访问的实体（用于验证或修剪的候选实体）
• gaps --可能已过时的易失性事实（版本、端口、路径、环境变量）
• all --合并报告-- 建议在会话启动时使用

______________________________________________________________________

consolidate --内存维护

刷新置信度评分，删除过时的事实，删除空实体，清理孤立关系，存档旧数据，检测近乎重复的数据。

定期运行或当内存变大时运行。被取代的（历史）事实仅在以下情况下存档 archiveDays 保存学习历史。

______________________________________________________________________

forget --删除事实

通过子字符串匹配替换实体中的事实。

事实被取代了（不是被硬删除了）——历史被保留了。使用 recall(mode="entity", include_history: true) 看到被取代的事实。

______________________________________________________________________

信心如何发挥作用

每个事实的置信度都是自动计算的：

confidence = sourceBase + recencyBonus

sourceBase (permanent floor):
  1 source  → 0.30
  2 sources → 0.42
  3 sources → 0.50
  5+ sources → 0.60

recencyBonus (decays over 90 days):
  just confirmed → +0.30
  30 days ago    → +0.21
  90 days ago    → +0.11
  180 days ago   → +0.04

关键设计决策： 长期的知识永远不会衰减到零。一个曾经陈述过的事实多年后仍然得分为0.30。只有最近的奖金会衰减——证据库是永久的。这可以防止常见的RAG问题，即有效但旧的信息被垃圾回收。

无论置信度如何，受保护的实体类型都不会被修剪： agent-self, person, project, preference, decision, organization, skill, constraint.

______________________________________________________________________

混合搜索的工作原理

每次搜索调用都会并行运行两个引擎，然后合并结果：

Query: "database port configuration"
         │
    ┌────┴─────────────┐
    │                  │
  BM25              Semantic
  (keyword)         (vector)
    │                  │
  Finds:             Finds:
  "database"    "listen address 3211"
  "port"        "server bind config"
  "configuration"  "networking setup"
    │                  │
    └────┬─────────────┘
         │
    Merge (alpha=0.6)
    → 60% semantic score + 40% BM25 score
         │
    Rerank by confidence × recency
         │
    Top-K results

它们共同涵盖了两端：确切的技术字符串和概念意义。

嵌入在第一次访问时延迟计算并缓存在 memory-embeddings.json实体更改时，缓存无效。

______________________________________________________________________

两层整合

灯（每次冲洗，5分钟节流）

• 所有活动事实的信心评分刷新

满（每24小时+按需通过 consolidate 工具）

1. 所有实体的信心刷新
2. 存档取代了超过180天的事实
3. 删除非受保护实体上陈旧的低置信度活动事实（>60天，\0.70）
4. 将旧交易所从热层（500个上限）归档到归档层
5. 根据文件系统验证文件实体（可选）

______________________________________________________________________

内置展示台

打开 http://localhost:3211/visualizer 在浏览器中以交互方式探索知识图。

特性

• 无限画布 --在任何方向上自由地摇动，没有界限。点网格SVG背景无限延伸。
• 防缩放缩放 --节点、标签和边在任何缩放级别都保持最小屏幕尺寸：

  nodeRadius = max(base / zoom^1.25, 9px / zoom)   → always ≥9px on screen
  fontSize   = max(base / zoom^1.15, 10px / zoom)  → always ≥10px on screen
  edgeWidth  = max(base / zoom^0.95, 0.8px / zoom) → always visible

• 按度径向布局 --具有最多关系的实体被放置在外环；中心附近的孤立节点集群：

  pct = 1 - rank / (N-1)   // rank 0 (most connected) → pct=1 → outermost
  r   = maxRadius × (0.12 + pct × 0.88)

• 节点拖动 --将任何节点拖动到自定义位置，保存到本地存储（键： v4)并在下次访问时恢复。
• 全屏幕模式 --展开到全视口、无边界的无限画布。
• 智能限制 --显示多达300个节点和600条边，而不会降低性能。

控制

节点颜色图例

______________________________________________________________________

数据格式

memory.json — 内存数据v7 （具有置信度、版本控制、多维标签和工作记忆会话的结构化事实）：

{
  "version": 7,
  "entities": [
    {
      "name": "forkscout-memory-mcp",
      "type": "service",
      "facts": [
        {
          "content": "TypeScript MCP server with JSON persistence",
          "confidence": 0.92,
          "sources": 3,
          "firstSeen": 1708000000000,
          "lastConfirmed": 1708600000000,
          "status": "active"
        },
        {
          "content": "Uses MemoryData v5 schema",
          "confidence": 0.65,
          "sources": 1,
          "firstSeen": 1707000000000,
          "lastConfirmed": 1707000000000,
          "status": "superseded",
          "supersededBy": "Schema v7 with multi-dimensional tags",
          "supersededAt": 1708600000000
        }
      ],
      "lastSeen": 1708600000000,
      "accessCount": 42,
      "tags": { "project": "forkscout", "scope": "project" }
    }
  ],
  "relations": [
    {
      "from": "forkscout-memory-mcp",
      "to": "TypeScript",
      "type": "uses",
      "weight": 0.95,
      "evidenceCount": 5,
      "lastValidated": 1708600000000,
      "createdAt": 1707000000000
    }
  ],
  "exchanges": [
    {
      "id": "ex_1708600000000_a1b2",
      "user": "How does contradiction detection work?",
      "assistant": "Three strategies: negation patterns, number/version conflicts, and topic overlap divergence...",
      "timestamp": 1708600000000,
      "sessionId": "session_abc",
      "importance": 0.8,
      "tags": { "project": "forkscout" }
    }
  ],
  "activeTasks": [
    {
      "id": "task_1708600000000_x1y2",
      "title": "Implement tagging system",
      "goal": "Add multi-dimensional tags to entities and exchanges",
      "status": "completed",
      "startedAt": 1708600000000,
      "lastStepAt": 1708603600000,
      "priority": 0.8,
      "importance": 0.9
    }
  ],
  "workingMemorySessions": {
    "session_abc": [
      {
        "content": "Started migrating schema to v7",
        "event_type": "action",
        "timestamp": 1708600000000
      },
      {
        "content": "Found contradiction in port facts — resolved to 3211",
        "event_type": "observation",
        "timestamp": 1708600100000
      }
    ]
  }
}

架构迁移

服务器在启动时自动迁移：

• v4 → v7：普通字符串事实→ 具有置信度、版本控制和标签的结构化事实
• 版本5 → v7：添加事实状态(active/superseded)，清洁 [SUPERSEDED] 文本前缀，添加标签
• v6 → v7：添加 tags 对于实体和交易所，添加 workingMemorySessions

迁移是非破坏性的。所有数据均已保存。

实体类型（30）

核心： person · project · technology · preference · concept · file · service · organization · agent-self · other

认知： goal · task · plan · skill · problem · hypothesis · decision · constraint

经验： event · episode · outcome · failure · success

环境： resource · state · signal

关系类型（120+）

结构： uses · owns · works-on · prefers · knows · depends-on · created · related-to · part-of · manages · dislikes · learned · improved

有意： pursues · plans · executes · blocks · requires · prioritizes

时间/原因： causes · results-in · leads-to · precedes · follows

学习： observed · predicted · confirmed · contradicted · generalizes · derived-from

演出 succeeded-at · failed-at · improved-by · degraded-by

内存： remembers · forgets · updates · replaces

沟通： discusses · mentions · references · quotes · summarizes · clarifies · asks-about · answers

社会： collaborates-with · reports-to · reviews · approves · delegates-to · advises · teaches · learns-from

技术： implements · extends · overrides · calls · imports · exports · configures · deploys · monitors · tests · documents · generates · parses · validates · transforms

状态/生命周期： initializes · activates · deactivates · pauses · resumes · completes · fails · retries · cancels · schedules

空间/组织： contains · located-in · belongs-to · groups · categorizes · indexes · archives

比较： similar-to · different-from · better-than · worse-than · equivalent-to · alternative-to · complement-to

因果关系延伸： enables · prevents · triggers · mitigates · amplifies · constrains · supports · contradicts-with

认识论： believes · doubts · assumes · hypothesizes · verifies · refutes · questions · trusts

目标/动机： motivates · discourages · aligns-with · conflicts-with · depends-on-goal

______________________________________________________________________

协议

MCP结束 可流式传输的HTTP （无状态模式）：

• POST /mcp --JSON-RPC 2.0请求
• 回复：SSE已包装(event: message\ndata: {json}\n\n)
• 通知（否 id)：HTTP 202 Accepted
• 方法： initialize, tools/list, tools/call

没有持久连接。没有WebSocket。一个请求=一个响应。可轻松部署在任何反向代理或负载均衡器后面。

______________________________________________________________________

项目结构

forkscout-memory-mcp/
├── src/
│   ├── server.ts         # HTTP server, MCP transport, consolidation timer, graceful shutdown
│   ├── store.ts          # MemoryStore — CRUD, search, contradiction detection, consolidation, tag filtering
│   ├── tasks.ts          # TaskManager — active task tracking, auto-expiry, similarity detection
│   ├── tools.ts          # 9 MCP tool registrations with Zod schemas
│   ├── types.ts          # Type definitions (MemoryData v7, Entity, Fact, Relation, Exchange, etc.)
│   ├── embeddings.ts     # Xenova/all-MiniLM-L6-v2 embedding + BM25 hybrid search engine
│   ├── working-memory.ts # Session-scoped working memory (push/get/clear, last 25 events)
│   └── visualizer.ts     # Infinite canvas knowledge graph visualizer (SVG, radial layout)
├── Dockerfile            # Single-stage: oven/bun:1 (Debian) — runs TypeScript natively, no build step
├── docker-compose.yml    # Volume: memory-data → /data, network: forkscout_default
├── package.json
├── tsconfig.json
└── .dockerignore

Docker基础镜像： 用途 oven/bun:1 （Debian），而不是Alpine。Alpine因musl-libc与Xenova ONNX运行时不兼容而被删除。

______________________________________________________________________

为什么不直接使用矢量数据库？

矢量数据库（Pinecone、Chroma、Weaviate）非常适合文档检索。它们是代理记忆的错误工具。

正确的思维模式： 矢量数据库是一个库 （存储文档以供查找）。 forkspect记忆mcp是一个大脑 （保持信念，从纠正中学习，跟踪信心，记住对话，并在浏览器中可视化完整的知识图）。

______________________________________________________________________

语义三元组vs RDF vs Graph DB vs本项目

三重模型

关系知识的基本单位是 三倍: Subject → Predicate → Object

forkscout-memory-mcp  →  uses  →  TypeScript

在本项目中： { from: "forkscout-memory-mcp", type: "uses", to: "TypeScript" }

资源描述框架

RDF是使用URI和共享词汇表的三元组的正式标准。这个项目是三重的，但 不是RDF --没有SPARQL，没有本体层，没有URI要求。专为快速代理工作流设计的轻量级。

图形数据库

Graph DB（Neo4j、JanusGraph）存储针对大规模遍历查询优化的节点和边。这个项目使用了一个存储在JSON中的图形模型——不是一个大规模的图形引擎，而是一个简单的可移植性和零依赖性。

这个项目实际上是什么

forkspect内存mcp是一个 混合代理存储系统 分层在图形之上：

1. 图形层 --实体+类型化关系（120+种类型）
2. 信仰层 --具有可信度、时效性和来源计数的事实
3. 修订层 --旧的信仰被取代而不是被删除
4. 对话层 --通过混合搜索存储和搜索重要交易所
5. 执行层 --活动任务在会话中存活
6. 工作层 --短期会话上下文在重启过程中持续存在

并排

一句话：这不仅仅是一个SPO图——它是SPO图加 信心、新近性、矛盾处理、纠正历史、对话记忆、工作记忆、任务跟踪和内置可视化工具.

______________________________________________________________________

许可证

麻省理工学院