sivtr

一个面向智能体和人的统一的记忆空间
让智能体和终端共享同一个上下文
你的 Agent 记忆，不必是一套笨重的知识系统。

简体中文 · English · Docs · 中文文档

---

Why do you need sivtr?

Developers and Agents often waste time rebuilding context that already exists: terminal errors, test output, tool logs, previous AI sessions. sivtr turns this local work into searchable memory, without forcing you to adopt a heavy knowledge system.

With sivtr, you can:

• Have the Agent fix the most recent failure without pasting logs yourself;
• Retrieve yesterday's test output, build errors, or key decisions in seconds;
• Jump from a summary back to the exact command output or Agent reply at the time;
• Save a useful set of results into a variable like @failures and keep using it in your next command.

[!IMPORTANT] For Agent workflows, install the sivtr CLI, register MCP with sivtr mcp install, and optionally use the built-in sivtr-memory skill. MCP is the primary path for Agents to read local evidence; the skill teaches it when and how to call it.

Features

• MCP-first Agent memory: one sivtr mcp install and the Agent calls search/show/zoom/filter/status/usage/stats tools directly—no need for you to paste logs.
• Preserving-output terminal capture: records commands, stdout/stderr, exit codes, working directory, and duration in Bash, Zsh, PowerShell, and Nushell; pipe and run write directly into the same archive.
• Unified local archive: all terminal and Agent sessions sync into a single archive.db first; providers only handle discovery and parsing, while search, filtering, export, TUI, MCP, and the Web API all share the same record model.
• 40+ Agent providers: Codex / Claude Code / Cursor / Dsh / Gemini / Goose / Hermes / OpenCode / OpenClaw / Grok / Pi / Qoder / Qoder-CN / Qwen, plus many more JSONL, SQLite, directory, and container formats—same registry and query surface.
• Precise evidence, not summaries: every hit lands on a stable ref you can show / zoom / filter on, or hand off to the next Agent.
• Named memory variables: save results as @failures, reuse @last, pipe with @, or take a subset with @failures[1,3..5].
• Usage and cost: extracts token usage from transcripts and computes cost with exact micro-USD integers and a built-in pricing snapshot; unknown prices are shown explicitly as unpriced, never guessed.
• Optional semantic / hybrid search: configure an OpenAI-compatible embedding endpoint to rank by vectors or fuse with RRF over BM25; without it, structured search remains fully usable.
• Stats, quality, and portable import/export: stats, secret findings, starred sessions, Claude.ai/ChatGPT JSON/ZIP import, and JSON/JSONL/Markdown/HTML export.
• Local Web UI: sivtr web provides a loopback dashboard and JSON API that read the same unified archive.
• Cross-device access: share a workspace read-only, browse another device with desk:... refs as if local; multiple devices can form a group that auto-syncs between members and levels out with a single sync.
• Configurable theme: [theme] mode = auto|dark|light, follows the system appearance automatically and detects truecolor.
• One-command install and diagnostics: sivtr setup installs hooks + MCP; sivtr doctor --fix auto-repairs.
• Human CLI still here: search / show / filter / nav, plus a TUI browser—useful, but not the main story.

Quick start

Install the prebuilt CLI (no Rust toolchain required):

cargo binstall sivtr

On Linux, cargo binstall installs the static musl build by default (independent of the system GLIBC version), from the same source as install.sh.

Other options:

cargo install sivtr                  # 从源码编译（需要 Rust）
curl -fsSL https://raw.githubusercontent.com/Ariestar/sivtr/main/install.sh | sh   # Linux/macOS/WSL 一行安装

Windows (PowerShell):

irm https://raw.githubusercontent.com/Ariestar/sivtr/main/install.ps1 | iex

Upgrade:

sivtr update    # 下载最新 release，SHA256 校验后原地替换

First-time install (hooks + MCP host):

sivtr setup             # hooks + MCP 宿主 + sivtr-memory skill（缺失时安装）
# 或分步：
sivtr init powershell   # 或 bash、zsh、nushell
sivtr mcp install       # 检测已装宿主；或 -p claude,cursor,codex,opencode,openclaw,grok,hermes,pi,qoder,qodercn,gemini,qwen,goose
npx skills add Ariestar/sivtr --skill sivtr-memory -g -y
sivtr doctor

Sync and inspect the archive:

sivtr sync
sivtr usage daily
sivtr stats
sivtr web

[!NOTE] On Windows, if sivtr init powershell reports that the profile was not loaded, just run Set-ExecutionPolicy -Scope CurrentUser RemoteSigned once to raise the current user's execution policy. sivtr does not modify the registry—hooks are only written into your PowerShell profile.

Agent memory (MCP)

This is the primary path. After sivtr mcp install, the Agent reads and writes local terminal and AI session memory through structured tools:

Tool	Purpose
sivtr_search	Find recent failures, decisions, commands
sivtr_show	Open the exact record/part behind a hit
sivtr_zoom	Expand surrounding context
sivtr_filter	Narrow the result set
sivtr_status	workspace / remote / origin status
sivtr_usage	token usage and model cost
sivtr_stats	archive activity, quality, and usage statistics

Optional skill (teaches the Agent when to invoke these tools):

npx skills add Ariestar/sivtr --skill sivtr-memory -g

Then just say:

修复最近的终端报错。先用 sivtr。

Agent should search local evidence, open sources, edit and verify — not ask you to paste logs.

CLI still available when needed:

sivtr s terminal --status failure --latest 5 --refs
sivtr s agent -m "TODO|decision|failed" --since today -f timeline

Examples

See Playbooks / Usage Examples for more complete walkthroughs.

Scenario	How you use it	Demo
Fix the most recent terminal error	Tell the Agent (MCP): Fix the most recent terminal error. Use sivtr first.
Resume after interruption	Tell the Agent: Continue. Use sivtr memory first.
Write a handoff for the next Agent	Tell the Agent: Write an evidence-backed handoff for the next Agent.
Generate a recent work timeline	sivtr s agent --since today --sort oldest -f timeline sivtr s terminal --since today --sort oldest -f timeline
Save results to a variable and continue processing	sivtr s terminal -m "panic" --save failures sivtr filter @failures --status failure --refs

Core Concepts

Concept	Meaning
WorkRecord	A useful work event: a terminal command, an Agent turn, a tool call, or a captured output block.
WorkPart	A command, output, assistant reply, tool output, or error within a Record. Use it when you only want a useful fragment rather than the whole event.
WorkRef	A stable address for a precise piece of memory, e.g. pi/<session>/3/p1. Ideal for referencing, reproducing, and handing off.
WorkSet	The data behind memory variables like @last and @failures: an ordered set of refs that can be filtered, saved, sliced, piped, navigated, expanded, and displayed.

Variables:

Handle	Purpose
@last	The most recent search or projection result.
@name	A named variable created via --save name or sivtr var set name, e.g. @failures.
@name[1,3..5]	Pick only a few items from a saved variable.
@	Use the result passed by the previous command in the pipe.

Commands

For the full list of commands, subcommands, and options see the CLI Reference. Quick reference of core commands:

Install & Maintenance

sivtr setup                              # 一键配置：环境检测 + hooks + MCP + skill + smoke
sivtr doctor --fix                       # 诊断并自动修复 binary/config/hooks/providers
sivtr mcp install -p claude,cursor,codex # 指定宿主注册 MCP（不指定则检测已装的）
sivtr update                             # 自更新到最新 release
sivtr config show                        # 查看配置（init 生成默认文件 / edit 用 $EDITOR 打开）

Day-to-day Usage

sivtr                                    # TUI workspace 浏览器
sivtr run cargo test                     # 执行命令并捕获输出（run <COMMAND> [ARGS...]）
sivtr s terminal --status failure --latest 5 --refs   # 最近 5 个失败终端事件
sivtr s agent -m "panic|TODO" --since today -f timeline # 今天的 agent 决策时间线
sivtr show @last                         # 打开上次搜索结果内容
sivtr show desk:terminal/session_42/3    # 打开远端精确 ref
sivtr copy                               # 复制最近命令块
sivtr copy out 2..4                      # 第 2~4 块的输出
sivtr copy in --pick --regex panic       # 交互挑选含 panic 的输入块
sivtr copy cmd --pick                    # 交互挑选命令本身
sivtr copy 3 --print                     # 第 3 块直接打印到 stdout
sivtr usage daily --breakdown             # 按天/provider/model 查看 token 与成本
sivtr usage session codex/<session-id>    # 查看单个 session 的用量
sivtr export sessions --format markdown   # 导出 archive 中的 session
sivtr import sessions --provider chatgpt conversations.json

Remote & Collaboration

sivtr share                              # 交互选择 workspace 创建只读分享
sivtr share invite <share> --expires 10m # 签发单次 invite（stdout = bare key）
sivtr remote add desk <invite-key>       # 把队友的 share 挂成本机 remote `desk`
sivtr group create <name>                  # 建组并贡献当前 workspace（如 create team）
sivtr group invite <name> --expires 1d --max-uses 10   # 签发多设备 join 链接
sivtr group join <invite-key>            # 加入并贡献自己的 workspace
sivtr group members team                 # 组内成员与其贡献
sivtr s <peer>:terminal --status failure --latest 5 --refs  # 读队友记忆像读本地

Remote Access

Two devices running sivtr can read each other's workspace sessions as if they were local — for collaborative development: when you want to see a teammate's terminal output or AI sessions, you don't have to leave your own machine.

Refs are unified as origin:body:

codex/4                 # 本机当前 workspace
docs:codex/4            # 本机另一个 workspace（按目录名）
desk:terminal/...       # remote add 得到的远端名
alice/sivtr:hermes/...  # device/workspace 坐标

On the device holding the workspace:

sivtr share                   # 交互选择 workspace（Enter = 当前）；只创建 share
sivtr share invite <name>     # 签发单次 invite（stdout = bare key）
sivtr ws list                 # 查看本机 workspace origin 标签

On the other device:

sivtr remote add desk <invite>   # 粘贴 `sivtr share invite` 输出的 bare key
sivtr s desk:terminal --status failure --latest 5 --refs
sivtr show desk:terminal/session_42/3
sivtr zoom desk:terminal/session_42/3 -C 2
sivtr nav desk:terminal/session_42/3 +1 --refs
sivtr copy desk:terminal/session_42/3 --print

Sharing is opt-in and read-only; by default, common secrets are redacted before data leaves the local machine. Remote transfers go over encrypted iroh; a daemon is started automatically when needed. Unregistered origins will error out — register a remote with sivtr remote add, or list local workspaces with sivtr ws.

Groups

For long-term memory sharing across 2+ devices, form a group instead of individually share-ing and mounting: each device in the group contributes its workspace; members auto-sync and can read each other anytime.

# 组主（owner）在 A 机上：
sivtr group create <name>      # 建组并贡献当前 workspace
sivtr group invite <name>      # 签发多设备 join 链接（stdout = bare key）

# 成员在 B 机上：
sivtr group join <invite>      # 加入并贡献自己的 workspace
sivtr group list               # 所有组
sivtr group members <name>     # 组内成员与其贡献
sivtr group sync <name>        # 手动拉一次成员清单

# 日常使用：像本地一样读队友的记忆
sivtr s <peer>:terminal --status failure --latest 5 --refs

The owner manages the group: rename to change the name, remove <group> <peer> to kick someone out; when the owner leaves (leave), the entire group is dissolved. Every member change is automatically synced to the whole group — no manual refresh needed.

Supported Sources

Source	What's supported
Terminal	Bash, Zsh, PowerShell, Nushell shell hooks; pipe and run capture.
Codex	Local rollout/session JSONL files.
Claude Code	Local transcript/session files.
Cursor	Local Cursor agent transcript JSONL.
OpenCode	Local session database.
OpenClaw	Local OpenClaw agent SQLite (+ legacy JSONL).
Hermes	Local Hermes state.db (JSONL under sessions/ is residual).
Grok	Local Grok agent sessions (~/.grok, configurable via GROK_HOME).
Dsh	Local Dsh agent sessions.
Gemini	Local Gemini CLI sessions.
Goose	Local Goose agent sessions.
Pi	Local Pi agent session logs.
Qoder / Qoder-CN	Local Qoder and Qoder-CN agent sessions.
Qwen	Local Qwen Code sessions.
More providers	Amp, Aider, Antigravity, Copilot, Forge, gptme, iFlow, Kimi, Kiro, OpenHands, Poolside, RooCode, Trae, Vibe, VSCode Copilot, Windsurf, Zed, Zencoder, etc.
Web import	JSON/ZIP exports from Claude.ai and ChatGPT, written to the archive via sivtr import sessions.

Docs

• Docs: https://sivtr.pages.dev/
• Chinese docs: https://sivtr.pages.dev/zh-cn/
• Playbooks: https://sivtr.pages.dev/zh-cn/playbooks/
• CLI Reference: docs-site/src/content/docs/reference/cli.md
• Memory skill: skills/sivtr-memory

Development

See CONTRIBUTING.md for environment setup, PR conventions, and coding guidelines.

cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace

Docs site:

cd docs-site
bun install --frozen-lockfile
bun run build

Repo layout:

crates/sivtr-core/  core model、provider parsers、archive、usage、search、config
src/                CLI commands、TUI、shell hooks、hotkey integration
docs-site/          Astro/Starlight documentation site
editors/vscode/     AI session picker 的 VS Code bridge
skills/             bundled agent skills