Skip to content

Commit 49fa378

Browse files
committed
feat(respire): 新增 respire 本地加密记忆插件(hooks+skill)
1 parent daf8fde commit 49fa378

12 files changed

Lines changed: 1164 additions & 12 deletions

File tree

‎assets/respire/icon.png‎

101 KB
Loading
Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
{
2+
"name": "respire",
3+
"version": "0.1.0",
4+
"description": "respire memory for ZCode: every-round title-tier recall, one-prefix store, model-optional degradation. Register on rsrs.rs for sync; the sidecar model is an optional boost.",
5+
"description_i18n": {
6+
"en": "respire local encrypted memory: every-round title-tier recall, one-prefix store, Stop storage check. Fully usable without the sidecar model.",
7+
"zh-CN": "respire 本地加密记忆:每轮标题档自动召回、一句「记:」落库、Stop 存储检查,不装模型也完全可用。"
8+
},
9+
"author": {
10+
"name": "risense-ai",
11+
"url": "https://github.com/risense-ai"
12+
},
13+
"homepage": "https://github.com/risense-ai/respire-zcode",
14+
"repository": "https://github.com/risense-ai/respire-zcode",
15+
"license": "MIT",
16+
"keywords": [
17+
"memory",
18+
"respire",
19+
"rsrs",
20+
"recall",
21+
"hooks",
22+
"local-first"
23+
],
24+
"skills": "./skills",
25+
"hooks": "./hooks/hooks.json"
26+
}
Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Changelog
2+
3+
All notable changes to this project are documented in this file.
4+
The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).
5+
6+
## [0.1.0] - 2026-10-23
7+
8+
### Added
9+
10+
- 首版:respire(rsrs)记忆层接入 ZCode——SessionStart 简则注入、UserPromptSubmit 每轮标题档召回、「记:」一前缀落库回执、Stop 存储检查(block 续跑一轮)。
11+
- ZCode 协议适配(对照 respire-qoder 0.6.3 骨架):
12+
- 输出走严格 JSON:文本 → `{"additionalContext":…}`(ZCode 忽略纯文本 stdout,已核 runtime 源码);
13+
- Stop 阻塞用 `{"decision":"block","reason":…}`(ZCode 枚举 approve|block,不收 `deny`);
14+
- 数据目录探测 `RESPITE_DATA` → `ZCODE_PLUGIN_DATA` → 脚本目录;hooks.json 仅 ZCode schema 收录字段,不带 `commandWindows`。
15+
- `scripts/validate_plugin.py`(结构/清单/hooks/输出契约/敏感扫描)、`scripts/package.sh`+`release.yml`(tag→release,与 dimcode 同口径)、`tests/test_hooks.sh`(stdin 模拟断言+`--store` 写探针自清理)。

‎external_plugins/respire/LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 fslong
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎external_plugins/respire/README.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# respire
2+
3+
> Store on inhale, recall on exhale — local encrypted memory for ZCode.
4+
5+
`respire` (CLI: `rsrs`) is a standard ZCode plugin that wires the respire memory engine into the agent loop with command hooks: title-tier recall injected every turn, one-prefix storing, and a Stop storage check. Local-first, end-side encrypted, cloud LWW sync.
6+
7+
Sibling builds for other hosts: [respire-dimcode](https://github.com/risense-ai/respire-dimcode) (Dim) · [respire-qoder](https://github.com/risense-ai/respire-qoder) (Qoder) · [respire-workbuddy](https://github.com/risense-ai/respire-workbuddy) (WorkBuddy) · [respire-zcode](https://github.com/risense-ai/respire-zcode) (this plugin's standalone repo).
8+
9+
## Fully usable without the model (degradation is a first-class citizen)
10+
11+
- **Registration, login, sync and recall never depend on a local model** — the plugin works right after install; without the model the engine automatically falls back to the lexical tier.
12+
- BGE-M3 is a **pure optional boost**: for better semantic recall run `rsrs model install && rsrs model activate m3`. The plugin notices it is missing and mentions it once in-session; installing or not never blocks anything.
13+
14+
## What happens after install
15+
16+
| When | Behavior |
17+
| --- | --- |
18+
| `SessionStart` | Injects a short memory playbook (when to recall, how to store, red lines); **one probe, three states** — signed-out gets registration guidance, an empty store (<10 records) gets first-day seeding/import guidance, a missing semantic model gets the **optional** install hint; zero interruption otherwise |
19+
| `UserPromptSubmit` | Automatic `rsrs recall --titles`: **title-tier injection** — score + 8-char short id + title only; the agent fetches bodies on demand with `rsrs show <id>`. Default is **direct output without threshold filtering**; noise is bounded by the engine's own skip gate + limit 5 + title tier |
20+
| Prompt starts with `记:` / `存:` / `remember:` | Stores directly via `rsrs remember … --importance important` and returns a receipt; when the dedup judge finds a similar record nothing is written — candidates are relayed for the model to decide (`--parent` attach or `--force` write); the receipt requires the model to extract a "subject + action + result" fact sentence and `retitle` |
21+
| `Stop` (agent finished) | **Storage check**: `{"decision":"block","reason":…}` continues one round, nudging the model to store new facts/decisions/agreements/lessons/pitfalls; pure Q&A or chat ends directly. Loop-safe: the continuation round carries `stop_hook_active=true` and passes through (the host caps continuations at three; this layer nudges at most once per turn); throttle `store_nudge_every` (1 = every turn, N = every N turns, 0 = off); if the store saw a write in the last 10 minutes (engine `list`), it stays silent |
22+
| Prompt starts with `/nomem` | Skips recall for that turn |
23+
| `skills/respire` | On-demand playbook (recall/remember/show/forget/sync and envelope parsing notes); **the skill is documentation — actions are hook-driven** |
24+
25+
## Install
26+
27+
Install directly from the official plugin market (**Settings → Plugins**, search respire). Alternatively add the standalone repo as a custom market: clone [risense-ai/respire-zcode](https://github.com/risense-ai/respire-zcode), then **Plugin Marketplace → Add → Add Plugin Marketplace** with the repo directory, and install from "Personal → risense-zcode".
28+
29+
## First use · three things
30+
31+
1. **Register & sign in** (works out of the box, no model needed): register at [rsrs.rs](https://rsrs.rs) → run `rsrs register` locally; day-to-day `rsrs login` via browser; autosync is always on, `rsrs sync` for manual sync, `rsrs status` for state.
32+
2. **Import existing rules and memory** (one-shot store, LLM extracts): paste this into a new ZCode task —
33+
34+
> Please import my existing rules and memory into respire: read one by one — `~/.zcode/AGENTS.md` (home rules, if present), workspace-root and per-project `AGENTS.md`, `~/.agents/skills/*/SKILL.md`; extract reusable facts, agreements, lessons and red lines (never passwords, ID numbers, card numbers, private keys — record only where they are stored), dedupe, and store them one by one with `rsrs remember` (`--importance important`, fact-sentence titles; on dedup candidates decide to attach or merge), then give me a list.
35+
36+
3. **Local model (optional boost)**: `rsrs model install && rsrs model activate m3` — fully usable without it; install for better semantic recall.
37+
38+
## Tuning (optional)
39+
40+
`hooks/respire.config.json` inside the installed plugin directory (missing = all defaults; new sessions pick it up; **never touches login or account**; template: `hooks/respire.config.example.json`):
41+
42+
| Field | Default | Meaning |
43+
| --- | --- | --- |
44+
| `rsrs` | `""` | Engine path; empty = auto-detect (PATH → `~/.local/bin` → `~/.rsrs/bin`) |
45+
| `recall_threshold` | `0.0` | Recall floor; **0 = off by default (engine direct output)** |
46+
| `recall_limit` | `5` | Top N per turn |
47+
| `min_prompt_chars` | `2` | Skip 1-char prompts |
48+
| `session_rules` | `true` | Inject the SessionStart playbook |
49+
| `budget_chars` | `1500` | Per-turn injection budget |
50+
| `enabled` | `true` | **Master switch**: false = fully silent |
51+
| `store_nudge_every` | `1` | Stop-check throttle: 1 = every turn, N = every N turns, 0 = off |
52+
| `skip_prefixes` | `[]` | Host-internal prompts matching these prefixes are neither recalled nor stored |
53+
| `log` | `true` | `hook.log` trace in the data dir (rotated at 256KB) |
54+
55+
## Dependencies, network and side effects
56+
57+
- **Required dependency**: the respire engine (`rsrs` CLI, npm package [`@rsrsai/cli`](https://www.npmjs.com/package/@rsrsai/cli), MIT, by risense-ai — the same vendor as this plugin). When missing, the plugin injects the install command (`npm i -g @rsrsai/cli@latest`) for the agent to run in-session; auto-detected at PATH, `~/.local/bin`, `~/.rsrs/bin`.
58+
- **Network**: installing the engine uses npm; `rsrs sync` talks to the respire cloud (end-side encrypted; account optional — local-only mode works). No other network access.
59+
- **Model/API**: optional BGE-M3 sidecar model downloaded via `rsrs model install`; no external LLM API is called by this plugin.
60+
- **Command execution**: hooks invoke `rsrs` (`recall`/`remember`/`list`/`status`) as subprocesses.
61+
- **File writes**: `hook.log` and `.nudge_counter` in the plugin data dir (or the hooks directory as fallback); nothing else.
62+
- **Hooks**: `SessionStart`, `UserPromptSubmit`, `Stop` — all fail-open (empty output + exit 0 on any error, never blocks a session).
63+
- **No MCP server**, no telemetry.
64+
- **Assets**: `assets/respire/icon.png` is the project logo of risense-ai's respire (MIT). Third-party services referenced: rsrs.rs (account/sync, optional), npm registry (engine install).
65+
66+
## Self-test
67+
68+
```bash
69+
python3 ../../scripts/validate.py # marketplace structure (repo root)
70+
bash tests/test_hooks.sh # read-only behavior assertions against a real engine
71+
bash tests/test_hooks.sh --store # adds a write probe (writes the real store, then rsrs forget cleanup)
72+
```
73+
74+
## License
75+
76+
MIT
Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# respire
2+
3+
> 吸即存,呼即取——给 ZCode 装上本地加密记忆。
4+
5+
`respire`(CLI 名 `rsrs`)是 ZCode 标准插件:以命令钩子把 respire 记忆引擎挂进 agent 循环——每轮标题档自动召回、「记:」一前缀即落库、Stop 存储检查。本地优先、端侧加密、云端 LWW 同步。
6+
7+
其他宿主的姊妹版本:[respire-dimcode](https://github.com/risense-ai/respire-dimcode)(Dim)· [respire-qoder](https://github.com/risense-ai/respire-qoder)(Qoder)· [respire-workbuddy](https://github.com/risense-ai/respire-workbuddy)(WorkBuddy)· [respire-zcode](https://github.com/risense-ai/respire-zcode)(本插件的独立源仓)。
8+
9+
## 不装模型完全可用(降级是一等公民)
10+
11+
- **注册、登录、同步、召回全不依赖端侧模型**——装完插件即可用,未装模型时引擎自动走词面档。
12+
- BGE-M3 是**纯可选增强**:想要更好的语义召回再 `rsrs model install && rsrs model activate m3`,插件检测到未装会在会话内提示一句,装与不装都不报错、不拦路。
13+
14+
## 装上后发生什么
15+
16+
| 时机 | 行为 |
17+
| --- | --- |
18+
| `SessionStart` | 注入记忆层简则(何时翻忆、如何落库、红线);**一次探测三态**——未登录附注册引导、库空(<10 条)附首日存料与导入引导、缺语义模型附**可选**装法;常态零打扰 |
19+
| `UserPromptSubmit` | 自动 `rsrs recall --titles`:**标题档注入**——只给分数+8 位短 id+标题,正文由 agent `rsrs show <id>` 按需取;默认**直出不过滤**,噪音边界=rsrs skip 门+limit 5+标题档 |
20+
| `prompt` 以「记:」「存:」「remember:」开头 | 直接 `rsrs remember … --importance important` 落库并回执;判后即存判为相似时**不写入**、回执转述候选(`--parent` 挂靠或 `--force` 直写),由模型决断;回执硬约束 AI 抽「主语+动作+结果」事实句 `retitle` 替换暂拟题 |
21+
| `Stop`(AI 干完活) | **存储检查**:`{"decision":"block","reason":…}` 续跑一轮,提示模型把本轮新的**事实/决定/约定/教训/踩坑**分条 `rsrs remember`;闲聊无新事实则直接结束。防循环:续跑轮 stdin 带 `stop_hook_active=true` 即放行(宿主限续跑至多三次,本层每轮至多催一次);节流 `store_nudge_every`(默认 1=每轮,N=每 N 轮,0=关);近 10 分钟本库有过落库(问引擎 `list`)则不再催 |
22+
| `prompt` 以 `/nomem` 开头 | 本轮跳过召回 |
23+
| `skills/respire` | 按需加载的操作法(recall/remember/show/forget/sync 与信封解析要点);**注意技能只是说明书,动作全由钩子驱动** |
24+
25+
## 安装
26+
27+
官方插件市场直接安装(**设置 → 插件** 搜索 respire)。也可自建市场源安装:克隆 [risense-ai/respire-zcode](https://github.com/risense-ai/respire-zcode) 后,在 **插件市场 → 添加 → 添加插件市场** 粘贴仓目录,再在「个人 → risense-zcode」安装。
28+
29+
## 首次使用 · 三件事
30+
31+
1. **注册登录**(开箱即用,不依赖模型):[rsrs.rs](https://rsrs.rs) 注册 → 本机 `rsrs register`;日常 `rsrs login` 浏览器授权;autosync 常开,`rsrs sync` 手动同步,`rsrs status` 查态。
32+
2. **导入既有记忆与规则(一次成库,LLM 代抽)**:开个 ZCode 新任务粘贴下面整段——
33+
34+
> 请把本机的既有规则与记忆导入 respire:逐个读取——`~/.zcode/AGENTS.md`(家目录规则,若在)、工作区根与各项目的 `AGENTS.md`、`~/.agents/skills/*/SKILL.md`;抽出可复用的事实、约定、教训与红线(口令、证件号、卡号、私钥一律排除、只记位置),去重后用 `rsrs remember` 分条存入(`--importance important`、标题按事实句;判重给候选先决断挂靠或合并),存完给我一份清单。
35+
36+
3. **端侧模型(可选增强)**:`rsrs model install && rsrs model activate m3`——不装完全可用,想要更好语义召回再装。
37+
38+
## 调优(可选)
39+
40+
插件安装目录下 `hooks/respire.config.json`(缺失即全默认,改完新会话生效;**不涉及登录与账号**;模板见 `hooks/respire.config.example.json`):
41+
42+
| 字段 | 默认 | 含义 |
43+
| --- | --- | --- |
44+
| `rsrs` | `""` | 引擎路径;空 = 自动探测(PATH → `~/.local/bin` → `~/.rsrs/bin`) |
45+
| `recall_threshold` | `0.0` | 召回下限;**0=默认关(rsrs 直出)**,设正数才启用过滤 |
46+
| `recall_limit` | `5` | 取前 N 条 |
47+
| `min_prompt_chars` | `2` | 1 字才跳,2 字起即查 |
48+
| `session_rules` | `true` | 是否注入 SessionStart 简则 |
49+
| `budget_chars` | `1500` | 单轮注入总预算 |
50+
| `enabled` | `true` | **总开关**:false=全线静默 |
51+
| `store_nudge_every` | `1` | Stop 存储检查节流:1=每轮、N=每 N 轮、0=关 |
52+
| `skip_prefixes` | `[]` | 宿主内部提示白名单:命中前缀的 prompt 不召回不落库 |
53+
| `log` | `true` | 数据目录 `hook.log` 留痕(超 256KB 清轮) |
54+
55+
## 依赖、网络与副作用
56+
57+
- **必需依赖**:respire 引擎(`rsrs` CLI,npm 包 [`@rsrsai/cli`](https://www.npmjs.com/package/@rsrsai/cli),MIT,与本插件同属 risense-ai)。缺失时插件会在会话内注入装法(`npm i -g @rsrsai/cli@latest`)由 agent 代装;探测顺序 PATH → `~/.local/bin` → `~/.rsrs/bin`。
58+
- **网络**:装引擎走 npm;`rsrs sync` 连 respire 云端(端侧加密;账号可选,纯本机模式可用)。除此之外无网络访问。
59+
- **模型/API**:可选 BGE-M3 端侧模型经 `rsrs model install` 下载;本插件不调用任何外部 LLM API。
60+
- **命令执行**:钩子以子进程调用 `rsrs`(`recall`/`remember`/`list`/`status`)。
61+
- **文件写入**:插件数据目录(回退 hooks 目录)的 `hook.log` 与 `.nudge_counter`;无其他写入。
62+
- **钩子**:`SessionStart`、`UserPromptSubmit`、`Stop`——全部 fail-open(任何异常空输出+exit 0,绝不拦会话)。
63+
- **无 MCP server**、无遥测。
64+
- **素材**:`assets/respire/icon.png` 为 risense-ai respire 项目 logo(MIT)。引用的第三方服务:rsrs.rs(账号/同步,可选)、npm registry(引擎安装)。
65+
66+
## 自测
67+
68+
```bash
69+
python3 ../../scripts/validate.py # 市场结构(仓根)
70+
bash tests/test_hooks.sh # 行为只读断言(需真机 rsrs 引擎)
71+
bash tests/test_hooks.sh --store # 加写探针(写真库→回执→rsrs forget 自清理)
72+
```
73+
74+
## License
75+
76+
MIT
Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
{
2+
"hooks": {
3+
"SessionStart": [
4+
{
5+
"matcher": "startup|resume|clear|compact",
6+
"hooks": [
7+
{
8+
"type": "command",
9+
"command": "python3 \"${CLAUDE_PLUGIN_ROOT}/hooks/respire.py\" SessionStart || python \"${CLAUDE_PLUGIN_ROOT}/hooks/respire.py\" SessionStart",
10+
"timeout": 20,
11+
"statusMessage": "respire: injecting memory playbook"
12+
}
13+
]
14+
}
15+
],
16+
"UserPromptSubmit": [
17+
{
18+
"hooks": [
19+
{
20+
"type": "command",
21+
"command": "python3 \"${CLAUDE_PLUGIN_ROOT}/hooks/respire.py\" UserPromptSubmit || python \"${CLAUDE_PLUGIN_ROOT}/hooks/respire.py\" UserPromptSubmit",
22+
"timeout": 20,
23+
"statusMessage": "respire: recalling memory"
24+
}
25+
]
26+
}
27+
],
28+
"Stop": [
29+
{
30+
"hooks": [
31+
{
32+
"type": "command",
33+
"command": "python3 \"${CLAUDE_PLUGIN_ROOT}/hooks/respire.py\" Stop || python \"${CLAUDE_PLUGIN_ROOT}/hooks/respire.py\" Stop",
34+
"timeout": 20,
35+
"statusMessage": "respire: checking storage"
36+
}
37+
]
38+
}
39+
]
40+
}
41+
}
Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
{
2+
"rsrs": "",
3+
"recall_threshold": 0.0,
4+
"recall_limit": 5,
5+
"min_prompt_chars": 2,
6+
"session_rules": true,
7+
"budget_chars": 1500,
8+
"enabled": true,
9+
"skip_prefixes": []
10+
}

0 commit comments

Comments
 (0)