diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 24d34bc..c116b09 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "session-recall", - "version": "0.4.0", - "description": "Shared semantic recall over local Claude Code and Codex session history. Bundles MCP search tools, a deep-recall subagent, a trigger skill, and a background freshness hook.", + "version": "0.5.0", + "description": "Shared semantic recall over local Claude Code and Codex session history. Bundles MCP search tools, a deep-recall subagent, a trigger skill, an agent-driven setup skill (/session-recall:setup), and a background freshness hook.", "author": { "name": "max" } } diff --git a/README.md b/README.md index 1b4d4d8..97e090a 100644 --- a/README.md +++ b/README.md @@ -139,6 +139,12 @@ for months of transcripts, seconds after that. Then start a new session — MCP servers and skills load at session start, not on install. +Prefer to let the agent do the setup? After installing the plugin, say +"set up session-recall" (or run `/session-recall:setup`): the agent asks the +three onboarding questions in chat — language, local or cloud embedder, +solo or team — runs the commands itself, and finishes with a health check +and a real search over your history. + **Codex** — the `.codex-plugin/plugin.json` manifest is ready to drop into a local repo or your personal marketplace; see the [local plugin installation guide](https://learn.chatgpt.com/docs/build-plugins#install-a-local-plugin-manually). diff --git a/commands/setup.md b/commands/setup.md new file mode 100644 index 0000000..9a75a14 --- /dev/null +++ b/commands/setup.md @@ -0,0 +1,8 @@ +--- +description: Guided session-recall setup — language, embedder, optional team mode +--- + +Read and follow the plugin's `setup` skill (skills/setup/SKILL.md): ask the +user the three onboarding questions in chat (interaction language, local or +cloud embedder, solo or team), then run the commands from the skill yourself +and finish with `session-recall health` plus one real search. diff --git a/skills/setup/SKILL.md b/skills/setup/SKILL.md new file mode 100644 index 0000000..67f7a45 --- /dev/null +++ b/skills/setup/SKILL.md @@ -0,0 +1,92 @@ +--- +name: setup +description: Set up or reconfigure session-recall for the user — install, pick the interaction language, choose a local or cloud embedder, optionally enable team sharing. Trigger when the user asks to "set up session-recall", "настрой session-recall", install it, change its embedder/language, or enable sharing with a colleague. The user answers three questions in chat; you run the commands. +--- + +# Agent-driven setup + +You are the installer. Ask the user the three questions below IN CHAT, in the +user's language, then run the commands yourself. Never invent flags — every +command you need is written here. All state lives outside the repo +(`~/.local/share/session-recall/`), so nothing here touches their project. + +## 0. Install (skip if `session-recall --help` already works) + +```bash +pipx install git+https://github.com/AbsoluteMode/session-recall +``` + +Plugin (gives the agent recall tools + auto-fresh index): in Claude Code run +`/plugin marketplace add AbsoluteMode/session-recall` then +`/plugin install session-recall`; other MCP hosts register +`session-recall-mcp` directly. + +## 1. Three questions (ask in chat, one message) + +1. **Language** you mostly work in with your agent (en / zh / ru / other) — + picks the bundled embedding model; specialists exist for en and zh, + everything else gets the multilingual model. +2. **Embedder: local or cloud?** + - *local, zero setup* — bundled CPU model, free, nothing leaves the machine, + coarser ranking. Also fine: an already-running ollama/lmstudio is picked + up automatically. + - *cloud (Voyage)* — noticeably better ranking + reranker; transcript + surface text is sent to the provider; needs `VOYAGE_API_KEY`. +3. **Solo or team?** Solo is the default (nothing is shared, nothing listens). + Team = pair with specific colleagues; every answer to them passes a secret + scanner and the user's explicit approval. + +## 2. Apply + +Language (always): + +```bash +session-recall setup --lang --yes +``` + +`--yes` also runs the first index. Warn first when the history is large +(`setup` prints the size): on the bundled CPU model months of history can +take a while; that is normal, later runs are incremental. + +Cloud embedder: the key must NOT pass through you when avoidable — ask the +user to add `export VOYAGE_API_KEY=…` (from voyageai.com) to their shell +profile themselves, then re-run `session-recall index` in a fresh shell. +Never write an API key into any file inside a repository. + +Local server instead of the bundled model (optional): +`export SESSION_RECALL_EMBED=ollama` (needs `ollama pull nomic-embed-text`). + +## 3. Team (only if chosen) + +Transport first — both peers, same choice (README → Team mode has the +self-host recipes): + +```bash +export SESSION_RECALL_RELAY_URL=https://relay.example.com # their relay +# or a folder both peers sync: +export SESSION_RECALL_SHARE_TRANSPORT_DIR=~/Sync/sr-share +``` + +Then the ceremony — the invite code and the SAS check travel between the +HUMANS out-of-band (that is the security model; do not relay them yourself): + +```bash +session-recall share init +session-recall share invite # user A: hand the code to the colleague +session-recall share join # user B +session-recall share complete # user A +session-recall share trust # BOTH, after the SAS codes match aloud +session-recall share allow --to # default is deny-all +session-recall share pause # any time: stop answering +``` + +## 4. Verify — always finish with this + +```bash +session-recall health +``` + +GREEN/AMBER verdict → done; show the user one real search over their own +history (`session-recall search "…"` with something they actually worked on) +so the first impression is a hit, not a config file. RED → the verdict names +the broken dimension and the fix; resolve it before declaring success.