savecontext (Greenfieldlabs Inc)

保存上下文

AI编码代理的操作系统

](https://www.npmjs.com/package/@savecontext/mcp)   

网站 • • 板条箱.io • 更新日志

______________________________________________________________________

SaveContext为AI编码代理提供了他们缺少的操作层——会话、问题跟踪、时间跟踪、计划、语义搜索和多代理协调，所有这些都存储在SQLite中，并通过本地CLI提供(sc)或任何MCP兼容客户端。

没有云帐户。没有API密钥。没有费率限制。

Quick Install

cargo install savecontext-cli && sc init

Requires Rust. See Installation for alternatives.

______________________________________________________________________

快速开始

# Start a session
sc session start "building auth system"

# Save context as you work
sc save auth-choice "JWT with refresh tokens" -c decision -p high
sc save login-done "Login endpoint complete with rate limiting" -c progress

# Track work with issues
sc issue create "Add auth middleware" -t task -p 3
sc issue create "Fix token refresh bug" -t bug -p 4
sc issue claim SC-a1b2

# Check current state
sc status

要连接MCP兼容客户端（Claude Code、Cursor、Codex、Gemini等）：

bunx @savecontext/mcp

然后将其添加到客户端的MCP配置中——请参阅 配置.

______________________________________________________________________

为什么要保存上下文？

问题

AI编码代理在对话之间失去了所有上下文。当窗口关闭时，决策、进展和理由都消失了。问题跟踪存在于代理无法本地使用的外部工具中。当多个代理在同一个项目上工作时，没有协调——它们重复工作，产生冲突，没有共享状态。

解决方案

SaveContext是一个与AI编码代理一起运行的本地操作层。它提供了范围工作的会话、跟踪任务的问题、规范特征的计划、通过意义查找过去决策的语义搜索以及协调原语，因此多个代理可以在不相互干扰的情况下工作。所有内容都存储在您计算机上的单个SQLite数据库中。

如何比较

______________________________________________________________________

你能做什么

会议和背景

会议组织你的工作，并将背景范围定在重要的事情上。上下文项在对话中持续存在——你的代理永远不会忘记决策、进度或笔记。

sc session start "payment integration"
sc save stripe-approach "Event-driven with webhooks, not polling" -c decision -p high
sc save api-keys "Use test key sk_test_..." -c config
sc checkpoint create "pre-refactor" --include-git

# Later — resume where you left off
sc session list --search "payment"
sc session resume sess_abc123

# Find past context by meaning, not exact keywords
sc get -s "how do we handle stripe webhooks"

问题跟踪

通过史诗、依赖关系、优先级、标签和多代理协调进行全面的问题跟踪。特工可以申请工作，追踪阻断者，看看准备好了什么。

# Create an epic with subtasks
sc issue create "Epic: Auth System" -t epic -p 3
sc issue create "Add JWT types" -t task --parent SC-a1b2
sc issue create "Auth middleware" -t task --parent SC-a1b2
sc issue create "Login endpoint" -t task --parent SC-a1b2

# Add dependencies between issues
sc issue dep add SC-c3d4 --depends-on SC-a1b2

# See what's ready to work on (unblocked + unassigned)
sc issue ready

# Claim and complete
sc issue claim SC-c3d4
sc issue complete SC-c3d4 --reason "Implemented with RS256 signing"

# Analytics
sc issue count --group-by status
sc issue stale --days 7
sc issue blocked
sc issue dep tree

计划和史诗

创建规范，将其与实施问题联系起来，并通过史诗般的完成来跟踪进度。

sc plan create "Q1 Auth Overhaul" -c "## Goals
- Replace session auth with JWT
- Add MFA support
- SSO integration"

# Link issues to plans
sc issue create "Epic: JWT Migration" -t epic --plan-id plan_xyz

# Epic progress tracked automatically
sc issue show SC-a1b2
# Progress: 3/5 tasks (60%)
#   Closed:      3
#   In progress: 1
#   Open:        1

语义搜索

通过意义而不是关键字查找过去的决定。智能搜索自动分解多词查询，调整阈值，并在需要时扩展范围。

sc get -s "database connection pooling strategy"
sc get -s "auth middleware rate limiting"   # Auto-decomposes into terms + bigrams
sc get -s "postgres" --search-all-sessions  # Search across all sessions

# Optional: higher quality search
ollama pull nomic-embed-text

智能上下文注入

将最相关的上下文注入到AI代理的当前上下文窗口中。Smart prime使用时间衰减、优先级、类别权重和可选的语义增强对每个上下文项目进行评分，然后应用MMR多样性重新排名，并将项目打包到令牌预算中。

# Ranked context within 4000 token budget (default)
sc prime --smart --compact

# Tight budget — only the most important items
sc prime --smart --compact --budget 1000

# Boost items related to a specific topic
sc prime --smart --compact --query "authentication"

# Aggressive recency bias (3-day half-life vs default 14)
sc prime --smart --compact --decay-days 3

# JSON output with scoring stats
sc prime --smart --json

评分公式： temporal_decay * priority_weight * category_weight * semantic_boost

多智能体协调

多个代理可以同时处理同一个项目。每个代理都从共享队列中声明工作，以防止冲突。

# Agent 1 claims work
SC_ACTOR=claude-agent-1 sc issue next-block --count 3

# Agent 2 claims different work
SC_ACTOR=codex-agent-2 sc issue next-block --count 3

# See who's working on what
sc issue list -s in_progress

远程访问

从任何计算机访问SaveContext数据。通过SSH代理运行命令或在机器之间同步完整的JSONL导出。

# Configure remote host
sc config remote set --host myserver.com --user shane

# Run any sc command on remote
sc remote status
sc remote session list
sc remote issue list -s open

# Sync data between machines
sc sync push        # Export local → SCP to remote → import
sc sync pull        # Export remote → SCP to local → import

时间跟踪

记录与问题和计费周期相关的计费小时数。跨项目跟踪时间、审查摘要和批量发票已完成的工作。

# Log hours
sc time log 4 "Auth middleware implementation" --period "CLIENT-2026-001"
sc time log 1.5 "Bug fix" --issue SC-a1b2 --period "CLIENT-2026-001"

# Review
sc time list --period "CLIENT-2026-001"
sc time summary --period "CLIENT-2026-001"
sc time total --status logged                  # Unbilled hours

# Invoice a billing period
sc time invoice --period "CLIENT-2026-001"

技能和钩子

在没有npm/bun的情况下安装工作流技能和钩子。直接从GitHub下载。

sc skills install                    # Auto-detect tools (Claude Code, Codex, Gemini, Factory AI), install everything
sc skills install --tool claude-code # Target specific tool
sc skills install --tool factory-ai  # Factory AI tools
sc skills install --path /custom/path # Override skills directory
sc skills status                     # Check what's installed
sc skills update                     # Re-download latest

______________________________________________________________________

设计原则

1.CLI优先

所有的业务逻辑都存在于Rust中。MCP服务器是一个精简的包装器，它将每次调用委托给CLI。使用 sc 直接从您的终端，或连接任何兼容MCP的客户端——无论哪种方式，行为都是一样的。

sc issue list              # Direct CLI
bunx @savecontext/mcp     # MCP clients get the same commands

2.仅限本地

没有云，就没有账户。所有数据都存储在一个具有WAL模式的SQLite数据库中，以实现快速并发读取和防崩溃写入。可选的基于SSH的同步(sc sync push/pull)允许您在没有任何云服务的情况下在机器之间传输数据。

~/.savecontext/
└── data/
    └── savecontext.db    # Everything lives here

3.代理人优先

每个命令都支持 --json 用于结构化输出。当stdout通过管道传输时，输出自动为JSON——不需要标志。 --silent 仅返回用于脚本编写的ID。结构化错误包括机器可读代码、提示和类似的ID建议。

sc issue list              # TTY → human-readable table
sc issue list | jq         # Piped → auto-JSON
sc issue create "Bug" --silent  # Returns: SC-a1b2

意图检测使常见同义词标准化，因此代理不需要记住规范值：

4.非侵入性

SaveContext从不运行git命令，从不自动提交，也从不安装钩子。它只触及 ~/.savecontext/。您的回购保持干净。

5.智能搜索

内置的Model2Vec嵌入可以在零配置的情况下立即工作。多词查询被自动分解为术语和二元组，单独搜索，并通过互易秩融合进行融合。阈值会动态调整。安装Ollama可获得更高质量的结果。任何一层都不需要API密钥。

sc get -s "authentication strategy"          # Built-in embeddings, adaptive threshold
sc get -s "auth middleware rate limiting"     # Auto-decomposes into subqueries + RRF
ollama pull nomic-embed-text                 # Optional: upgrade quality
sc get -s "authentication strategy"          # Now uses Ollama automatically

______________________________________________________________________

命令

完整的标志参考 cli/README.md中的代理集成模式 cli/AGENTS.md.

会话

上下文项目

问题

问题分析

依赖关系和标签

检查点

内存（跨会话持久）

时间跟踪

计划

项目

系统

全球旗帜

______________________________________________________________________

安装

CLI（主）

Rust命令行界面(sc)是所有SaveContext操作的真实来源。

# From crates.io
cargo install savecontext-cli

# Or build from source
git clone https://github.com/greenfieldlabs-inc/savecontext.git
cd savecontext/cli && cargo build --release
cp target/release/sc /usr/local/bin/sc

# Verify
sc --version

MCP 服务器

MCP服务器为说 模型上下文协议。需要 包子 以及上面的CLI。

curl -fsSL https://bun.sh/install | bash   # Install Bun (if needed)
bunx @savecontext/mcp                       # Run the MCP server

语义搜索（可选）

ollama pull nomic-embed-text   # Higher quality search via Ollama

SaveContext包括内置的本地嵌入（~15ms），可以立即工作。Ollama在可用时添加了更高质量的层（~50ms）。看 cli/README.md HuggingFace和其他供应商。

______________________________________________________________________

配置

将SaveContext添加到MCP客户端：

Claude Code

{
  "mcpServers": {
    "savecontext": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@savecontext/mcp"]
    }
  }
}

配置位置： ~/.claude.json （全球）或 .mcp.json （项目）

Cursor

{
  "mcpServers": {
    "savecontext": {
      "command": "bunx",
      "args": ["@savecontext/mcp"]
    }
  }
}

VS Code

{
  "mcp": {
    "servers": {
      "savecontext": {
        "type": "stdio",
        "command": "bunx",
        "args": ["@savecontext/mcp"]
      }
    }
  }
}

OpenAI Codex

[mcp_servers.savecontext]
args = ["@savecontext/mcp"]
command = "bunx"
startup_timeout_ms = 20_000

Gemini CLI

gemini mcp add savecontext --command "bunx" --args "@savecontext/mcp"

Factory

droid mcp add savecontext "bunx @savecontext/mcp"

Zed

{
  "context_servers": {
    "SaveContext": {
      "source": "custom",
      "command": "bunx",
      "args": ["@savecontext/mcp"]
    }
  }
}

Other MCP clients (Cline, Windsurf, JetBrains, Roo Code, Augment, Kilo Code, etc.)

大多数MCP客户端使用相同的JSON格式：

{
  "mcpServers": {
    "savecontext": {
      "command": "bunx",
      "args": ["@savecontext/mcp"]
    }
  }
}

GUI apps (Claude Desktop, Perplexity, LM Studio, BoltAI)

GUI应用程序可能不会继承shell的PATH。使用bunx的完整路径：

{
  "mcpServers": {
    "savecontext": {
      "command": "/Users/YOUR_USERNAME/.bun/bin/bunx",
      "args": ["@savecontext/mcp"],
      "env": {
        "PATH": "/Users/YOUR_USERNAME/.bun/bin:/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin"
      }
    }
  }
}

通过以下方式找到你的发髻路径： which bunx

Compaction Settings

控制SaveContext在对话窗口填满之前保留上下文的时间：

{
  "mcpServers": {
    "savecontext": {
      "command": "bunx",
      "args": ["@savecontext/mcp"],
      "env": {
        "SAVECONTEXT_COMPACTION_THRESHOLD": "70",
        "SAVECONTEXT_COMPACTION_MODE": "remind"
      }
    }
  }
}

______________________________________________________________________

仪表盘

用于可视化管理会话、问题、计划和内存的本地web界面。

bunx @savecontext/dashboard         # Starts on port 3333
bunx @savecontext/dashboard -p 4000  # Custom port

从与CLI相同的SQLite数据库读取(~/.savecontext/data/savecontext.db).

______________________________________________________________________

状态行

在终端中显示实时会话信息。适用于任何支持生命周期挂钩的工具——请参阅 docs/HOOKS.md 对于模板。

bunx @savecontext/mcp@latest --setup-statusline

# To remove
bunx @savecontext/mcp@latest --uninstall-statusline

显示：会话名称、上下文使用情况、成本、持续时间和更改的行。

How it works

PostToolUse Python钩子在每次SaveContext操作时将会话信息写入本地缓存文件。Claude Code的原生状态行在每个提示时从缓存中读取。每个终端都有自己的缓存密钥用于隔离。

支持的终端： Terminal.app、iTerm2、Kitty、Alacrity、GNOME终端、Konsole、Windows终端等。

手动超控： export SAVECONTEXT_STATUS_KEY="my-session"

需要Python 3.x。 安装脚本将安装 statusline.py 和 update-status-cache.py 到 ~/.savecontext/.

______________________________________________________________________

技能和代理模板

技能教AI代理如何使用SaveContext。安装它们，以便您的代理自动了解工作流。

bunx @savecontext/mcp@latest --setup-skill              # MCP mode (default)
bunx @savecontext/mcp@latest --setup-skill --mode cli    # CLI mode
bunx @savecontext/mcp@latest --setup-skill --mode both   # Both
bunx @savecontext/mcp@latest --setup-skill --sync        # Update all configured tools

代理模板： 复制 AGENTS.md 到项目根目录获取通用引用，或使用 CLAUDE.md 作为克劳德代码的具体示例。

______________________________________________________________________

建筑

AI Coding Agents (Claude Code, Cursor, Codex, Gemini, etc.)
          |                              |
          | MCP Protocol                 | Direct Bash
          v                              v
+-----------------------+    +---------------------+
|  MCP Server (TS)      |    |                     |
|  @savecontext/mcp     |--->|   Rust CLI (`sc`)   |
|  (thin wrapper)       |    |   Source of truth   |
+-----------------------+    |   45+ commands      |
                             +----------+----------+
                                        |
                                        v
                             +-----------------------+
                             |  SQLite Database      |
                             |  ~/.savecontext/      |
                             |  data/savecontext.db  |
                             +-----------------------+

数据流

Action                     Command                  Storage
────────────────────────────────────────────────────────────────────
Start session       →   sc session start      →   SQLite INSERT
Save context        →   sc save               →   SQLite INSERT + embed queue
Search context      →   sc get -s "query"     →   Vector search + SQLite
Create issue        →   sc issue create       →   SQLite INSERT
Claim issue         →   sc issue claim        →   Atomic UPDATE (assign + status)
MCP tool call       →   bridge.ts → sc        →   Same path as direct CLI

原则

• CLI优先 --所有的业务逻辑都存在于Rust中。新功能登陆 sc 第一。
• 仅限本地 --没有云，就没有账户。所有数据都保留在您的机器上。
• SQLite+WAL --快速并发读取，单作者，防崩溃。
• MCP电桥 --TypeScript服务器通过以下方式将每次工具调用委托给CLI server/src/cli/bridge.ts.

项目结构

cli/                          # Rust CLI (source of truth)
├── src/
│   ├── main.rs               # Entry point
│   ├── cli/commands/         # 45+ command implementations
│   ├── storage/              # SQLite database layer
│   ├── embeddings/           # Embedding providers (Ollama, HF)
│   └── sync/                 # JSONL import/export
└── Cargo.toml

server/                       # MCP server (delegates to CLI)
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── cli/bridge.ts         # Executes sc commands
│   ├── tools/registry.ts     # MCP tool definitions
│   └── lib/embeddings/       # Tier 1 (Model2Vec) embeddings
└── dist/

dashboard/                    # Local web UI
└── src/

______________________________________________________________________

文档

______________________________________________________________________

调试

使用详细标记来跟踪CLI正在做什么。输出会进入stderr，这样它就不会干扰stdout上的JSON。

sc get -s "auth decisions" -v      # info:  high-level actions (search started, stage matched)
sc get -s "auth decisions" -vv     # debug: decision points (thresholds, RRF scores, resolution sources)
sc get -s "auth decisions" -vvv    # trace: per-item details (sub-query hits, embedding dimensions)

示例 -vv 语义搜索的输出：

DEBUG sc::config: Session resolved session=sess_abc source="TTY status cache"
INFO  sc::cli::commands::context: Starting semantic search query="auth decisions" search_mode=Tiered
DEBUG sc::cli::commands::context: Stage 1: adaptive threshold search
DEBUG sc::cli::commands::context: Adaptive threshold computed top_score=0.138 adaptive_threshold=0.25 candidates=15 above_threshold=0
DEBUG sc::cli::commands::context: Stage 2: decomposition sub_query_count=3 sub_queries=["auth", "decisions", "auth decisions"]
DEBUG sc::cli::commands::context: RRF fusion complete unique_items=5 top_rrf_score=0.032
INFO  sc::cli::commands::context: Stage 2 matched (decomposed query) count=5

覆盖 RUST_LOG 为了实现完全控制（包括第三方机箱输出）：

RUST_LOG=debug sc get -s "test"          # Everything at debug (includes reqwest, hyper, rustls)
RUST_LOG=sc=trace sc save "key" "value"  # Only sc crate at trace

______________________________________________________________________

故障排除

错误包括机器可读代码、提示和类似的ID建议。使用 --json 用于结构化错误输出。

{
  "error": {
    "code": "ISSUE_NOT_FOUND",
    "message": "Issue not found: SC-xxxx",
    "retryable": false,
    "exit_code": 3,
    "hint": "Did you mean: SC-a1b2, SC-a1b3?"
  }
}

看 cli/AGENTS.md 用于完整的错误代码表和退出代码类别。

______________________________________________________________________

常见问题解答

数据存储在哪里？

所有数据都存在于一个SQLite数据库中：

~/.savecontext/
└── data/
    └── savecontext.db    # Sessions, context, issues, plans, memory, embeddings

没有云同步——你的数据永远不会离开你的机器。

我能用吗 sc 没有MCP服务器？

对。CLI是独立的，功能齐全。只有当您想通过MCP协议连接AI编码工具（Claude Code、Cursor等）时，才需要MCP服务器。

如何将SaveContext与AI编码代理一起使用？

两种方式：

1. MCP协议 --添加 bunx @savecontext/mcp 到客户端的配置。代理自动获得50多个工具。
2. 直接命令行界面 --支持bash的代理可以调用 sc 命令直接与 --json 用于结构化输出。

看 cli/AGENTS.md 用于集成模式和工作流。

依赖关系是如何工作的？

# Issue A depends on Issue B (A is blocked until B is closed)
sc issue dep add SC-a1b2 --depends-on SC-c3d4

# Now SC-a1b2 won't appear in `sc issue ready` until SC-c3d4 is closed
sc issue ready  # Only shows SC-c3d4

# Close the blocker
sc issue complete SC-c3d4

# Now SC-a1b2 is unblocked
sc issue ready  # Shows SC-a1b2

会话可以跨越多个目录吗？

对。使用 session add-path 对于单仓库或多项目工作流：

sc session start "full-stack feature"
sc session add-path /app/frontend
sc session add-path /app/backend
sc session add-path /shared/types

上下文和问题适用于会话中的所有路径。

语义搜索是如何工作的？

SaveContext使用具有智能搜索的两层嵌入系统：

• 第1层（内置）： Model2Vec嵌入，每个查询约15ms，无需设置即可立即工作
• 第2级（可选）： 奥拉玛与 nomic-embed-text，每次查询约50ms，结果质量更高

当Ollama可用时，SaveContext会自动使用它。如果没有，它将退回到内置嵌入。任何一层都不需要API密钥或云服务。

智能搜索运行一个4级级联：（1）具有自适应阈值的完整查询，（2）用于多词查询的子查询分解+互惠排名融合，（3）将范围扩展到所有会话，（4）最近错过建议。这意味着 sc get -s "auth middleware decisions" 即使没有单个项目与完整短语匹配，也会找到结果。

相同的嵌入式基础设施功能 智能prime (sc prime --smart)，它对所有上下文项进行评分和排名，以便最佳地注入代理的上下文窗口——请参见 智能上下文注入.

SaveContext使用哪些环境变量？

如何备份我的数据？

# Option 1: JSONL export
sc sync export

# Option 2: Copy the database file
cp ~/.savecontext/data/savecontext.db ~/backups/

______________________________________________________________________

自托管部署

在任何使用Docker的VPS或服务器上运行SaveContext。要使用的SSH sc 直接从本地计算机同步数据，并可选择公开仪表板。

# 1. Clone and start
git clone https://github.com/greenfieldlabs-inc/savecontext.git
cd savecontext/docker
docker compose up -d

# 2. Use it (default password: savecontext)
ssh -p 2222 root@localhost sc status
ssh -p 2222 root@localhost sc session list

默认SSH密码为 savecontext.将其更改为生产：

environment:
  - SSH_PASSWORD=your-secure-password

服务切换

# CLI-only (no dashboard)
ENABLE_DASHBOARD=false docker compose up -d

远程MCP访问

MCP客户端通过SSH管道连接——SSH处理身份验证和加密：

{
  "mcpServers": {
    "savecontext-remote": {
      "command": "sshpass",
      "args": ["-p", "savecontext", "ssh", "-p", "2222",
               "-o", "StrictHostKeyChecking=no", "root@your-server",
               "SAVECONTEXT_DB=/data/savecontext.db",
               "bun", "/opt/savecontext/server/dist/index.js"]
    }
  }
}

对于生产，使用SSH密钥而不是 sshpass.

机器之间的同步

# On your local machine, configure the remote
sc config remote set --host your-server --port 2222 --user root

# Push local data to server
sc sync push

# Pull server data to local
sc sync pull

数据保存在Docker卷中(sc-data).SQLite数据库位于 /data/savecontext.db 在容器内。

______________________________________________________________________

发展

# CLI
cd cli && cargo build --release && cargo test

# MCP Server
cd server && bun install && bun run build

# Dashboard
cd dashboard && bun install && bun dev

贡献

看 贡献.md 发展指南。

致谢

• 杰弗里·伊曼纽尔 --二层嵌入系统的Model2Vec方法
• 珠子 --CLI作为代理接口模式，激发了SaveContext CLI技能

许可证

AGPL-3.0