Thread Keeper

MCPAI代理

提供方 po4erk91

AI代理 stdio · 本地进程 API Key 社区 / 第三方 Claude DesktopClaudeCursorVS Code
查看接入方式

Multi-agent shared brain across Claude Code/Desktop, Codex, Antigravity CLI (agy), Gemini, Copilot, and VS Code. One local SQLite store for threads, notes, verbatim quotes, and a dialectic user model; spawn/broadcast/whisper/inbox multi-agent coordination primitives; autonomous b

一句话选型结论

按资料字段整理

Thread Keeper 属于AI代理类 MCP 服务器,stdio · 本地进程,API Key,可直接接入 Claude Desktop、Claude、Cursor 等,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类AI代理 传输方式stdio · 本地进程 鉴权API Key 部署方式本地部署
GitHub 星标 未标注 仓库热度,无公开仓库时显示未标注
工具数 未标注 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

AI代理
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量未标注暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

memory multi agent knowledge graph persistent context

支持客户端

适用场景

memorymulti agentknowledge graph

安装与配置

stdio · 本地进程 API Key
客户端在本机拉起子进程,数据不出本机
pipx install 'threadkeeper[semantic]' && thread-keeper-setup

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Cross-platform,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后随便调一个只读工具,确认能返回结果,再接入正式流程。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
给代理接外部能力

让代理在任务中途调用搜索、数据库等真实工具。

多步任务编排

把一串操作拆成步骤,由代理按顺序执行。

自动化重复流程

把固定流程交给代理跑,减少手工操作。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude Desktop、Claude、Cursor,换客户端不用重新研究配置。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 使用前要准备好API Key对应的凭据,并按最小权限配置。
  • 资料没标注工具数量,实际能力要装好后确认。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在AI代理场景里让模型直接调用外部能力的人。
  • 已经在用 Claude Desktop、Claude 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
Thread Keeper当前 未标注 stdio · 本地进程 本地部署 有 未标注
Filesystem 560c4363 13 未标注 本地部署 无 2026-05-17
Server Everything (everything) 11 stdio · 本地进程 本地部署 有 2026-05-17
Time 7365cb6d 2 SSE · 服务端推送 远程部署 有 2026-05-18
Everything Claude Code 未标注 stdio · 本地进程 本地部署 有 2026-05-17
Openmemory 557e1585 未标注 stdio · 本地进程 本地部署 有 2026-05-17

服务器档案

AI代理
字段来自项目仓库与公开索引,中文说明由本站标注
提供方po4erk91上游标注的维护方 po4erk91
分类AI代理本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式API Key远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · Cross-platform本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验未标注上游最后核验时间

详细介绍

150.1 KB
来自项目仓库与上游目录的原文,未做删改

thread-keeper

Multi-agent shared brain across Claude Code/Desktop, Codex,
Antigravity CLI (agy), Copilot, and VS Code.

Cross-session memory, self-improving skill loops, and inter-agent signaling —
one local MCP server turns parallel agent instances into a coordinated
multi-agent system instead of N isolated chats.

Every connected client (Claude Code, Claude Desktop, Codex CLI + desktop,
Antigravity CLI, Copilot, every MCP-aware VS Code extension)
shares one SQLite store, one set of threads, one user model, and one learning
loop that improves the skill library autonomously over time.

The brief format is dense — structural tags, opaque IDs, ~6 KB per
session-start injection. Optimized for agent consumption, not human reading.


Why

Every agent CLI starts cold. Context dies at session boundaries.
Skills you taught Claude don't transfer to Codex. Threads you closed
in yesterday's Antigravity chat are invisible to today's Copilot. Parallel
agent instances running the same task don't know about each other and
duplicate work or step on each other's writes.

thread-keeper is the substrate underneath. Three things that together
make it more than a memory store:

  • Collective memory — threads, notes, verbatim quotes, dialectic
    claims about you. Survives session, restart, CLI swap. One agent
    records, every other agent (any CLI) reads. The brief injected at
    session start gives a new agent everything the previous one knew.
  • Multi-agent coordination — spawn primitive launches child
    agents in parallel, each gets a self_cid + sees the same memory.
    broadcast / whisper / inbox / wait / ask / respond let
    concurrent sessions signal each other across CLIs. Parent /
    children / sibling agents become a coordinated swarm, not isolated
    chats.
  • Self-improving skill library — autonomous background loops
    (auto-review on thread close, shadow-review daemon, extract
    harvester, candidate-reviewer, weekly Curator, and a thread-janitor
    that auto-closes idle threads so abandoned work reaches the harvest
    path — closing is reversible, a note reopens a closed thread)
    materialize class-level skills as the agents work. Adapted to multi-CLI:
    SKILL.md is the primary write target and gets mirrored to every
    known/configured skills root simultaneously (~/.claude/skills/,
    ~/.codex/skills/, ~/.gemini/config/skills/ for Antigravity,
    existing ~/.agents/skills/, extra roots from
    THREADKEEPER_EXTRA_SKILLS_DIRS, and ~/.threadkeeper/skills/), with
    lessons.md as a fallback for CLIs without a native skills loader.

Foreground MCP servers also run a daily self-update check by default. Source
checkouts fast-forward their tracked git branch and reinstall the editable
package; PyPI/pipx/venv installs run pip install --upgrade in the current
interpreter environment only after the latest PyPI release files have matching
Integrity API provenance from the expected GitHub Trusted Publisher. Dirty or
diverged git checkouts are skipped rather than overwritten. Restarts are gated
on install/setup success plus a subprocess import smoke check, so a broken or
unverified update is recorded but the current server keeps running.
Interpreters without pip (uv-created or pipx venvs) install through
uv pip install --python when uv is available.
Upstream PyPI publishing is intentionally gated: green merge-to-main builds are
auto-tagged, but every upload pauses for a human approval on the protected
pypi GitHub Environment (a maintainer-signed annotated v* tag remains the
manual override path), as described in
docs/RELEASING.md.

They also run a twice-weekly installed-skill updater by default. It keeps all
configured CLI skill roots in sync, adopts newer local copies installed into a
non-primary root, and updates GitHub-backed skills when a tracked upstream
source changes.


Quickstart

The shortest path — PyPI + pipx (recommended):```bash
pipx install 'threadkeeper[semantic]' && thread-keeper-setup


`thread-keeper-setup` detects every CLI you have installed (Claude
Code / Claude Desktop / Codex CLI + desktop / Antigravity CLI `agy` /
Copilot / VS Code), registers the MCP server in each one's
config, copies hooks to
`~/.threadkeeper/hooks/`, and writes a managed instructions block into
each CLI's per-user instructions file (`CLAUDE.md` / `AGENTS.md` /
`copilot-instructions.md` — Claude Desktop and VS Code
have no global instructions file, so that step is skipped for them).
The generated MCP entry pins imports to this configured installation, so an
agent launched inside another thread-keeper checkout cannot load that checkout's
unmerged code against the live memory database.

Restart your CLI of choice. Hook-capable clients inject a brief on the first
message; hookless clients such as Codex and Antigravity CLI either follow the
managed instructions block and call `brief()` / `context()` before answering, or
— on hosts that support MCP **resources** — pull the brief as the read-only
`memory://brief` resource the host attaches automatically (see
MCP primitives).

The MCP initialization response also carries concise, static lifecycle guidance:
load the brief/context, open/note/close substantive threads, prefer read-only
resources for host-attached context, and use dry-run plus confirmation before
destructive maintenance. Hooks and the managed files remain reinforcement for
clients that do not surface server instructions.

### Alternative installs

If you don't have `pipx` and don't want to install it:```bash
# uv (Rust-fast Python tool runner) — no clone, single binary on PATH
uv tool install 'threadkeeper[semantic]' && thread-keeper-setup

# Plain pip into a venv
python3 -m venv ~/.threadkeeper-venv
~/.threadkeeper-venv/bin/pip install 'threadkeeper[semantic]'
~/.threadkeeper-venv/bin/thread-keeper-setup

For development (editable install from a git checkout) or to track the
bleeding edge:```bash

One-liner installer — clones to ~/thread-keeper, makes a venv,

editable-installs, wires every detected CLI. Idempotent — re-run to

update (it git-pulls + reinstalls).

curl -fsSL https://raw.githubusercontent.com/po4erk91/thread-keeper/main/install.sh | bash -s -- --semantic

Or fully manual

git clone https://github.com/po4erk91/thread-keeper ~/thread-keeper
cd ~/thread-keeper && python3 -m venv .venv
.venv/bin/pip install -e '.[semantic]'
.venv/bin/thread-keeper-setup


To preview without writing anything:```bash
thread-keeper-setup --dry-run

Multi-CLI integration

CLI MCP config Instructions file Hooks Transcripts ingested
Claude Code ~/.claude.json mcpServers ~/.claude/CLAUDE.md ~/.claude/settings.json hooks ~/.claude/projects/**/*.jsonl
Claude Desktop ~/Library/Application Support/Claude/claude_desktop_config.json mcpServers (macOS); %APPDATA%\Claude\… (Win); ~/.config/Claude/… (Linux) none (GUI-only) not supported by the app none — chats live in Electron IndexedDB
Codex (CLI + desktop) ~/.codex/config.toml [mcp_servers] (shared between CLI and Codex.app) ~/.codex/AGENTS.md not supported ~/.codex/sessions/**/rollout-*.jsonl
Antigravity CLI (agy) ~/.gemini/config/mcp_config.json mcpServers ~/.gemini/config/AGENTS.md not wired yet ~/.gemini/antigravity-cli/conversations/*.db (sqlite/protobuf, read-only: user prompts and final answers)
Copilot ~/.copilot/mcp-config.json mcpServers ~/.copilot/copilot-instructions.md ~/.copilot/hooks.json ~/.copilot/session-store.db (sqlite)
VS Code ~/Library/Application Support/Code/User/mcp.json servers (macOS); %APPDATA%\Code\User\mcp.json (Win); ~/.config/Code/User/mcp.json (Linux) none (per-workspace only) not supported none — extensions own their history

Every CLI that produces parseable transcripts feeds the same
dialog_messages table with a source tag, so dialog_search() finds
matches regardless of where the conversation happened. Claude Desktop and
the VS Code adapter are the exceptions — MCP registration only; their chats
don't reach the table for now (Electron IndexedDB on the Claude Desktop side;
per-extension stores on the VS Code side). Antigravity keeps one SQLite file
per conversation with protobuf step payloads; thread-keeper opens it read-only
(never creating WAL sidecars next to it) and keeps only user prompts and final
model answers, skipping tool calls and thinking.

VS Code's user-level mcp.json is the central host that every
MCP-aware VS Code extension
consumes — GitHub Copilot Chat, the
Anthropic Claude IDE plugin, the OpenAI Codex IDE plugin, Continue,
Cline, … — so a single registration there reaches all of them at once.

Adding a new CLI = one file under threadkeeper/adapters/ implementing
the CLIAdapter contract. See CONTRIBUTING.md.

Python MCP SDK surface

thread-keeper requires MCP Python SDK 2.3 or later (mcp>=2.3.0,<3). Its
stable Skills and durable Tasks extensions use the MCP 2026-07-28 extension surface, while tools,
resources, prompts, annotations, structured content, elicitation, and stdio
continue to use the same MCPServer instance.

MCP primitives (tools, resources, prompts, Apps, elicitation)

MCP has three server primitives. thread-keeper uses all three, mapped to the
read/act split, plus MCP elicitation for host-native confirmations:

Primitive Control What thread-keeper exposes When to use
Tools model-controlled (may act) the full surface — brief, note, spawn, search, curator_review, wikilink_health, … the agent decides to call them
Resources application-controlled, read-only memory://brief, memory://context, memory://dashboard, memory://agent-status the host attaches/pulls them automatically; capable hosts may subscribe
Prompts user-controlled templates review_recent_threads, run_library_curation, audit_threadkeeper the user runs them (Claude Code: /mcp__thread-keeper__)
MCP App host-rendered, display-only open_dashboard → ui://thread-keeper/dashboard a host that advertises MCP Apps opens the sandboxed dashboard

Resources back the genuinely read-only memory views with the same render
functions as the matching tools, so the content is identical — memory://brief
is brief(), memory://context is context(), and so on. The win is for
hookless CLIs: instead of depending on the agent remembering to call
brief() (agents focused on their task often skip it), a resource lets the host
surface memory as attachable / @-mentionable context through a mechanical
channel. The brief resource renders lean and agent-status uses a cached snapshot,
so an automatic host pull is side-effect-free.

Prompts turn the curation / audit / review flows into discoverable,
parameterized commands; each just drives the existing tools.

Portable dashboard App. open_dashboard is a read-only progressive
enhancement over the existing status data. In an MCP Apps-capable host it opens
ui://thread-keeper/dashboard in a sandboxed iframe and shows autonomous
loops, running children, budget state, task history, recent failures, and
recent materializations. It never sends prompts, transcripts, task-log text,
credentials, child identifiers, or local paths to the iframe. Loading and the
App's Refresh button only open the existing database in SQLite read-only mode;
they never bootstrap a session, reconcile tasks, start daemons, refresh process
RSS, or write telemetry.

This is portable across macOS, Windows, and Linux because it uses the existing
stdio server registration in the table above — no native app installation is
needed. If the host does not advertise the io.modelcontextprotocol/ui
extension with text/html;profile=mcp-app, open_dashboard returns a short
text fallback; use agent_status(json_output=True) or mp_dashboard() as the
tested fallback. The macOS menu-bar app remains an optional native frontend
over the same status data, not a requirement for this dashboard.

Elicitation is a client feature, not a server primitive. When a host
advertises form-mode elicitation, high-stakes mutations can pause for a
structured user choice instead of relying on an ignorable text nudge. The first
flow using it is dialectic_supersede: supported hosts get a flat
confirm/reject form before a user-model claim is replaced; unsupported hosts keep
the previous immediate tool behavior.

Everything here is additive and capability-gated: a host that advertises the
resources / prompts capabilities sees those primitives; one that advertises
MCP Apps gets the dashboard iframe; and one that advertises elicitation.form
gets structured confirmations for covered high-stakes writes.
Hosts without a capability fall back to the SessionStart hook plus the brief()
/ context() tools and the existing write behavior — same content, no
regression. Static URIs only for now (resource templates with {param} are
still unevenly supported across hosts).

MCP Skills extension

On MCP 2026-07-28 hosts, thread-keeper also advertises the stable
io.modelcontextprotocol/skills extension. skills/list pages the canonical
library deterministically, and skills/get returns the full manifest for one
skill. Each resource URI is origin-qualified, for example
skill://thread-keeper/release-check/SKILL.md, so hosts retain the server
identity alongside a possibly colliding skill name.

The manifest covers SKILL.md and every permitted file below references/,
templates/, scripts/, or assets/, with its byte length and a
sha256: digest. Files are individually available through ordinary
resources/read; traversal, undeclared files, and reads over 1 MiB are
rejected. Hosts should compare both size and digest before using a retrieved
file. The canonical directory is published once; the existing per-CLI
filesystem mirrors remain the fallback for clients that do not implement the
extension.

Discovery and resources/read are delivery only. Reading SKILL.md does not
activate it, approve its tools, record use telemetry, or approve supporting
files. Activation and any user approval remain responsibilities of the host's
skill-loading path.

MCP Tasks for headless spawn

Clients using MCP 2026-07-28 that advertise the
io.modelcontextprotocol/tasks extension can call spawn(..., visible=False)
as a durable asynchronous operation. The response is an opaque public task
handle; poll it with tasks/get and request cooperative cancellation with
tasks/cancel. Handles are bound to the authenticated caller (or the local OS
user for stdio), survive a host reconnect, and never expose the short internal
spawn ID. The server suggests a five-second polling interval.

Only headless spawn is task-eligible: visible Terminal.app work has no stable
process-group handle. tournament, tasks, task_logs, and the legacy custom
spawn lifecycle stay unchanged. Clients that do not advertise the extension
receive the existing synchronous spawn response, including on older protocol
versions. spawn does not pause for approval, so it deliberately does not
implement tasks/update or task enumeration.

Memory egress (cross-provider privacy)

thread-keeper is "one user model … shared across CLIs," and that sharing is by
design. The flip side: the most sensitive memory it holds — verbatim_user
quotes and the dialectic user-model (claims about you: style, values,
workflow) — is rendered into every brief(), and brief() is consumed by
whichever LLM vendor backs the active or spawned CLI. So by default, a quote
you said to Claude, or a trait inferred about you, can be transmitted to OpenAI
(Codex), Google (Antigravity), or Microsoft-GitHub (Copilot) on the
next session-start or spawn under that CLI. This is a deliberate default, not a
leak — but it's worth stating plainly, and it's controllable.

THREADKEEPER_MEMORY_EGRESS scopes the egress of personal-class memory
(verbatim + dialectic user-model). work-class (threads/notes/tasks) and
shared-class (skills/lessons/concepts) memory always egress.

Value Personal-class memory egresses to…
all (default) every vendor — current behavior, brief is byte-identical to pre-policy
same-vendor Claude / Anthropic only; omitted for OpenAI / Google / Microsoft CLIs
work-only no vendor — personal memory never leaves the machine

Under a restricted policy, the gated brief() drops the verbatim and
user_model (dialectic) sections and leaves a one-line egress policy=…: personal memory … withheld from disclosure so the consuming agent
knows personal context exists but was intentionally not sent. The native vendor
is Anthropic because the brief format and personal memory are authored in Claude
sessions. The gate applies on every consumption path: the foreground brief and
any spawned child — spawn() tells the child which vendor will consume its
brief, so a child spawned to a third-party CLI cannot retrieve more than the
policy allows for that vendor. Set it in ~/.threadkeeper/.env (a real env
override wins over .env):```bash
THREADKEEPER_MEMORY_EGRESS=same-vendor


### Project memory boundaries

Memory is also isolated by repository. thread-keeper derives a path-free
`prj_…` namespace from the repository remote (or, when no remote exists, its
Git history), so ordinary moves and Git worktrees retain one identity without
storing a local path. New project memory is scoped to that namespace; portable
memory must be explicitly written as `global` or `shared`.

`brief()`, `search()`, `dialog_search()`, resources, and learning-loop inputs
read the current project plus explicit global/shared rows. Set
`cross_project=True` on `search` or `dialog_search` only for deliberate
cross-project recall. Those results show `scope=`/`project=` provenance and
write a `cross_project_recall` audit event. The `memory_scope_status()` tool
shows the current namespace and the migration accounting.

Existing databases keep their memory recallable: legacy rows without reliable
repository provenance become `global`, as all memory effectively was before
namespaces, while tasks whose working directory still resolves are scoped to
their project; new memory is scoped from then on. The migration report records
the counts. A database that was already at schema v5 before namespaces existed
gets the namespace columns and this one-time backfill on its next start. Rows
explicitly marked `unresolved` stay excluded from automatic recall. This
boundary controls *which local memory is recalled*; it is separate from
`THREADKEEPER_MEMORY_EGRESS`, which controls whether personal memory may be
sent to another model provider.

---

## Core systems

### Spawn — primary parallelism primitive

`spawn(prompt, slim=True, role=..., visible=False, ...)` launches a child
Claude session via a `claude -p` subprocess. By default `slim=True`: the
child loads only the thread-keeper MCP, no embeddings, no third-party
servers. ~500 MB RSS versus ~1.3 GB for a full child. Heuristic for the
parent: N≥2 modular independent units of ≥5 min each = spawn signal.
Spawn also marks children with `THREADKEEPER_SPAWNED_CHILD=1`, so
autonomous learning daemons cannot recursively start inside review forks.
Codex children get the same isolation: `codex exec --ignore-user-config`
with only the user's provider settings and thread-keeper entry carried over,
and `enabled_tools` limited to the child's granted thread-keeper tools. Other
MCP servers, plugins and hooks from `~/.codex/config.toml` never start inside
a background child.

A daemon in the foreground parent measures combined child RSS every 10 s;
spawned children do not start their own `ps` polling loop, failed `ps` RSS
samples keep the last-known value, and the liveness sweep covers every open
task row so dead children stop counting against the cap. Admission control
refuses a new spawn that would exceed `THREADKEEPER_SPAWN_BUDGET_MB`
(3 GB default). Slim children that need semantic search delegate to the parent
via `search_via_parent` — no per-child copy of the embedding model. Admission
uses a short SQLite `BEGIN IMMEDIATE` reservation: `spawn()` re-checks the
budget and commits the child task row with its RSS estimate before `Popen`, so
two concurrent spawns cannot both squeeze through the cap, and no write lock is
held while the child launches.

When `cwd` is inside a Git checkout, `spawn()` also requires the source
checkout's tracked files to be clean, then starts the child from a unique
branch/worktree under `THREADKEEPER_TASK_LOG_DIR/worktrees/`. Parallel children
therefore never share a mutable checkout or Git index. Non-Git directories keep
their existing behavior; a dirty Git checkout is refused before a child starts.

Learning-loop children that name no `cwd` (Curator, shadow review, candidate
and dialectic review, probes, panels, the archivist) start in the owner-only
`/workspace` directory instead of the spawning process's working
directory. The daemon host keeps the directory of whichever session started it,
so these children used to run inside an unrelated user project, and a dirty Git
checkout there refused every loop spawn. Foreground spawns keep the caller's
directory, and callers that pass `cwd` (the Evolve reviewer and applier) are
unchanged.

The spawn wrapper also records each completed child's `duration_s`,
`tokens_in`, `tokens_out`, `tokens_total`, and `cost_usd` when the underlying
CLI emits a recognizable usage trailer. Optional daily ceilings
`THREADKEEPER_SPAWN_TOKEN_BUDGET` and
`THREADKEEPER_SPAWN_COST_BUDGET_USD` admission-deny new children once the
recorded 24h spend reaches the configured limit; both default to `0`
(disabled), so existing installs behave the same until a budget is set.
Claude children keep their positional prompt argv under a conservative
96 KiB byte ceiling; larger prompts are written to
`THREADKEEPER_TASK_LOG_DIR/.stdin.txt` with owner-only permissions and
fed on stdin, so Linux's per-argument `MAX_ARG_STRLEN` limit cannot turn a large
curator/reviewer prompt into an opaque `E2BIG` spawn failure.

Visible (`visible=True`, Terminal.app) children persist `pid=0`, so the
daemon resolves their live pid from the `--session-id` it carries in `ps`
argv and measures the real RSS tree — they count their true memory, not
the static estimate. A visible row whose session-id never resolves to a
live process is reaped once it outlives `THREADKEEPER_SPAWN_VISIBLE_TTL_S`
(1 h default; 0 disables), so an unresolvable row can't pin budget
capacity forever.

The same daemon is also a **wall-clock watchdog**: a child that hangs while
still alive — a wedged `WebFetch`/`gh`/`git`, an agent loop that never
converges, a prompt that never arrives — would otherwise stall its loop's
single-flight slot and burn tokens forever. Any child whose row outlives
`THREADKEEPER_SPAWN_MAX_RUNTIME_S` (1 h default; 0 disables) is `SIGTERM`'d,
then `SIGKILL`'d after `THREADKEEPER_SPAWN_KILL_GRACE_S` (10 s), and its row
is closed with the timeout `return_code` 124 so the loop's single-flight
releases. The watchdog then immediately starts a capped continuation retry:
the new child receives the original assignment plus the previous task/cid/log
and is instructed to inspect current workspace state, preserve completed work,
repair partial work, and continue rather than restart blindly.
`THREADKEEPER_SPAWN_TIMEOUT_RETRY_LIMIT` (default 3; 0 disables) bounds the
retry chain, with `THREADKEEPER_SPAWN_TIMEOUT_RETRY_DELAY_S` available for a
non-zero delay. Timed-out children are surfaced as `tasks_timed_out` in
`mp_dashboard` and `timed_out` in `agent_status`. `agent_status` and
`tk-agent-status` are observation-only and never terminate or respawn a
child; timeout enforcement and the continuation retry live solely in the
spawn-budget daemon.

`tk-agent-status` exposes autonomous learning loop status as structured JSON
or compact text for external monitors:```sh
tk-agent-status
tk-agent-status --json
tk-agent-status --cleanup-memory

apps/macos-agent-status/ contains a small macOS menu-bar app that polls this
command every 15 seconds and shows every autonomous learning loop: enabled/off,
running/idle/ready, last pass, backlog, and active child RSS when that loop has
spawned a worker. PyPI wheels and sdists also bundle the same Swift source under
threadkeeper/assets/macos-agent-status/, so a normal pipx/uv tool install
does not need a git checkout for the widget to build. Active loops are sorted
first (running, then ready), so background work stays at the top of the
panel. tk-agent-status --cleanup-memory runs the safe cleanup path used by the
widget: request server cache trims, apply the RSS guard, and remove orphan MCP
server processes without killing active spawned child agents. The popover also
has a power button that flips THREADKEEPER_DISABLE_BG_DAEMONS in
~/.threadkeeper/.env and requests a ThreadKeeper restart, so autonomous loops
can be paused or re-enabled without opening Settings. The menu-bar
status item is backed by AppKit NSStatusItem: it shows the black memorychip
icon while idle, then swaps fixed-center, synchronized gear frames whenever
running_loop_count reports at least one active autonomous loop. The status item is
icon-only; loop counts live in the popover and tooltip. The app also has a Clean
memory button, self-restarts when its own RSS crosses
THREADKEEPER_MENUBAR_RESTART_RSS_MB (1024 MB default), requests macOS
notification permission, and sends a notification when a newly completed
autonomous child task produces a useful result in recent_results; the first
poll only marks existing results as seen, so old completions do not spam
notifications. Status polling and cleanup commands run off the main actor, so
opening the popover does not wait for tk-agent-status --json. The header gear
opens a separate Settings window for
~/.threadkeeper/.env: a sidebar separates CLI Agents, LLM-backed Learning
Loop Agents, mechanical System Automation, Memory & Budgets, and Advanced
.env. Model catalogs come from installed CLIs at runtime and show installed
and latest official cloud versions, source, freshness, and discovery errors;
an Update button appears only when those versions differ and runs the CLI's
allowlisted vendor updater after confirmation. Each agent has its own CLI,
provider-filtered model, effort, inherited effective values, schedule, and
read/write impact. Guided controls are dropdown-only, with schedules labelled
in hours; custom values and raw unknown keys remain editable in Advanced .env
alongside three compact presets. Probe backlog is due objective
probes only, not every registered probe, so a healthy cooldown shows 0 due probes instead of looking stuck. On macOS, python -m threadkeeper.server
automatically installs and launches it on MCP startup. The installed app records
a source fingerprint, so package upgrades rebuild the helper even when an older
bundle has a newer file timestamp, then restart any stale running menu-bar
process. Set
THREADKEEPER_MENUBAR_AUTO_LAUNCH=0 to disable that behavior.

Auto Update

The MCP server starts an auto-update daemon in foreground parent processes.
By default it checks once per day (THREADKEEPER_AUTO_UPDATE_INTERVAL_S=86400):

  • editable git checkout: skip if tracked files are dirty, otherwise fetch the
    tracked remote branch, fast-forward with git pull --ff-only, reinstall the
    editable package, and run the configured post-update setup check;
  • installed package: run pip install --upgrade threadkeeper or
    threadkeeper[semantic] in the current interpreter environment, preserving
    semantic extras when they are already installed, but only after the candidate
    PyPI release's non-yanked files have PyPI Integrity API provenance from the
    expected GitHub Trusted Publisher (po4erk91/thread-keeper, publish.yml,
    environment pypi), then run the configured post-update setup check when the
    installed version changes.

Auto-update is standing consent for thread-keeper to fetch and run future
maintainer code. A packaged update whose provenance is missing, whose publisher
identity does not match policy, or whose attested subject digest does not match
PyPI metadata is refused before pip runs and is recorded as
auto_update_pass with mode=pip and refused. After a successful update, the
daemon exits the current MCP process by default so the host can restart it on
the new code. Before scheduling that exit, it imports threadkeeper.server in a
subprocess; install/setup/import failures are recorded as auto_update_pass
with restart=suppressed, and the current known-working process stays alive.
Post-update setup defaults to THREADKEEPER_AUTO_UPDATE_SETUP=check, which runs
thread-keeper-setup --dry-run only. It records setup=checked status=unchanged when configs already match and logs/records
status=changes_pending if MCP registrations, hooks, or managed instruction
blocks would be rewritten; it does not re-add config the user removed. Set
THREADKEEPER_AUTO_UPDATE_SETUP=apply to give standing consent for auto-update
to run the full setup writer after future successful updates, or skip to avoid
even the dry-run check.
Disable restart with
THREADKEEPER_AUTO_UPDATE_RESTART=0, or disable the updater entirely with
THREADKEEPER_AUTO_UPDATE_INTERVAL_S=0. The provenance gate is on by default;
THREADKEEPER_AUTO_UPDATE_VERIFY_PROVENANCE=0 is a break-glass opt-out for
private mirrors or disconnected installs. If a packaged release needs manual
rollback, pin the previous version explicitly, for example
pip install threadkeeper==. Each real check records an
auto_update_pass event that appears in dashboard/status telemetry.

Skill Update

…(正文过长,页面只展示前面部分,完整内容见仓库)

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
Thread Keeper 怎么安装?

在客户端按下面的安装命令接入:pipx install 'threadkeeper[semantic]' && thread-keeper-setup。装完在客户端配置里引用同一个包或端点。

Thread Keeper 怎么在 Claude Desktop、Claude、Cursor 里配置?

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

Thread Keeper 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

Thread Keeper 需要 API Key 吗?

资料标注需要API Key认证,使用前准备好对应凭据,并按最小权限配置。

Thread Keeper 支持哪些客户端?

资料标注支持 Claude Desktop、Claude、Cursor、VS Code、Cline、Gemini CLI;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

Thread Keeper 能提供哪些能力?

资料显示能力标签包括 memory、multi agent、knowledge graph、persistent context。具体工具清单以官方文档为准。

Thread Keeper 需要什么运行环境?

运行时为 Cross-platform;属于本地进程,需要在本机装好运行环境。

Thread Keeper 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 未标注。