sphica 0.6.48 → 0.6.50
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/plugin.json +1 -1
- package/.codex-plugin/plugin.json +1 -1
- package/README.md +2 -1
- package/dist/capture.js +14 -9
- package/dist/cli.js +39 -9
- package/dist/deliver.js +43 -19
- package/dist/git-worker.js +43 -16
- package/dist/mcp-record.js +499 -147
- package/dist/mcp.js +535 -338
- package/package.json +1 -1
- package/skills/export/SKILL.md +3 -1
- package/skills/fields/SKILL.md +3 -2
- package/skills/forget/SKILL.md +9 -4
- package/skills/glean/SKILL.md +12 -8
- package/skills/harvest/SKILL.md +9 -6
- package/skills/trace/SKILL.md +13 -8
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "sphica",
|
|
3
|
-
"version": "0.6.
|
|
3
|
+
"version": "0.6.50",
|
|
4
4
|
"description": "Records Claude Code and Codex sessions on your machine and keeps past implementation and decisions, with their sources, for your agent to find.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
package/skills/export/SKILL.md
CHANGED
|
@@ -38,7 +38,9 @@ Pass the repository root as `cwd` to every tool.
|
|
|
38
38
|
(CLAUDE.md, AGENTS.md, `.github/copilot-instructions.md`, a `SKILL.md`, anything under `.claude`, `.agents`, `.codex`, `.cursor`, a `skills` directory, or a plugin manifest directory) and Git's
|
|
39
39
|
own folder are refused
|
|
40
40
|
4. **Call `export`** with the chosen keys and the path. When it answers that nothing was exported, tell the owner the reasons it gives and
|
|
41
|
-
stop; write nothing.
|
|
41
|
+
stop; write nothing. A document has to fit one reply (about 29 KB): when it says the document would be over that, the owner picks
|
|
42
|
+
fewer decisions for this file, or several files; when it says one decision is over that on its own, that decision cannot be
|
|
43
|
+
exported, and `read` shows it. Otherwise its first line names the path and says whether it is a new file or replaces an existing one, and every line
|
|
42
44
|
after it is the document
|
|
43
45
|
5. **Show the owner the whole document**, and when it replaces a file, that file's current content too. Say that the quoted words, which may
|
|
44
46
|
include other people's comments, go into a file others can read. Ask whether to write it (AskUserQuestion in Claude Code). Without a clear
|
package/skills/fields/SKILL.md
CHANGED
|
@@ -19,8 +19,9 @@ on them, filled only when the conversation says it: trace saves a value only wit
|
|
|
19
19
|
|
|
20
20
|
## Flow
|
|
21
21
|
|
|
22
|
-
1. Call `fields` with the repository root as `cwd
|
|
23
|
-
|
|
22
|
+
1. Call `fields` with the repository root as `cwd`. A long table comes a page at a time: while a reply ends with a line that
|
|
23
|
+
names an `after`, call `fields` again with that `after`, until a reply ends without one
|
|
24
|
+
2. Show the table as it is, every page's rows under one header. Do not add, drop, or reword rows
|
|
24
25
|
3. When the owner asks how to add a field: they say it in a session (for example, "record the affected tenant as tenant on decisions"), and
|
|
25
26
|
the next `/sphica:trace` of that session saves it with their words. A field cannot be defined again or changed while fields are a trial
|
|
26
27
|
|
package/skills/forget/SKILL.md
CHANGED
|
@@ -3,7 +3,7 @@ name: forget
|
|
|
3
3
|
description: Removes sources the owner chooses from Sphica (a message, a pull request item, a file excerpt), with their search index entries and the bytes left in the database file, and judges the records that cited them again. The owner confirms in a dialog before anything is removed. Use only when the user explicitly asks to forget or delete something Sphica captured.
|
|
4
4
|
argument-hint: "<what to forget>"
|
|
5
5
|
disable-model-invocation: true
|
|
6
|
-
allowed-tools: AskUserQuestion, mcp__plugin_sphica_sphica__search, mcp__plugin_sphica_sphica__read, mcp__plugin_sphica_record__forget_preview, mcp__plugin_sphica_record__forget_apply, mcp__plugin_sphica_sphica__status
|
|
6
|
+
allowed-tools: AskUserQuestion, mcp__plugin_sphica_sphica__search, mcp__plugin_sphica_sphica__read, mcp__plugin_sphica_record__forget_preview, mcp__plugin_sphica_record__forget_apply, mcp__plugin_sphica_record__record_more, mcp__plugin_sphica_sphica__status
|
|
7
7
|
---
|
|
8
8
|
|
|
9
9
|
# forget — remove what should not have been kept
|
|
@@ -32,10 +32,15 @@ Pass the repository root as `cwd` to every tool.
|
|
|
32
32
|
**Never repeat a secret in your replies**: describe each source by its ref, kind, and where it is (`s12`, a message of 2026-09-20 in
|
|
33
33
|
this project, `file:config.md` lines 1-3)
|
|
34
34
|
2. **Confirm the list** with the owner (AskUserQuestion in Claude Code; in Codex, ask in the conversation and wait). Forget only what the owner picks
|
|
35
|
-
3. **Preview**: `forget_preview` with the refs. It lists
|
|
36
|
-
|
|
35
|
+
3. **Preview**: `forget_preview` with the refs. It lists every source that will be removed, how many records are affected and what becomes
|
|
36
|
+
of them (leave active, become active, change otherwise, keep their state), and then the records, those leaving active first. When the
|
|
37
|
+
reply ends with `call record_more with cursor: "..."`, read the rest of the records with `record_more` until a reply names no cursor.
|
|
38
|
+
Show the owner the sources, the counts, and the records that leave active
|
|
39
|
+
4. **Apply**: `forget_apply` with the same refs. The host shows the owner a dialog with every source and the counts (and as many of the
|
|
40
|
+
records as fit), asking to type the number of sources; nothing is removed
|
|
37
41
|
without that answer. Answering it is the owner's act: never ask the owner to tell you the number so you can answer for them
|
|
38
|
-
5. **Report** what `forget_apply` returned, as it says it
|
|
42
|
+
5. **Report** what `forget_apply` returned, as it says it: what was forgotten and whether the deleted text was cleared come first, and
|
|
43
|
+
`record_more` reads on when the records did not fit
|
|
39
44
|
|
|
40
45
|
When `forget_apply` says the host cannot ask directly, the host has no confirmation dialog (some Codex versions): tell the owner to run
|
|
41
46
|
`/sphica:forget` in Claude Code. When it says clearing did not finish (usually another session reading the database): run `forget_apply` with
|
package/skills/glean/SKILL.md
CHANGED
|
@@ -3,7 +3,7 @@ name: glean
|
|
|
3
3
|
description: Adds evidence and corrections to existing Sphica records, or keeps something the owner remembers, only from sources the owner points to (an issue or pull request, a file in the repository, the owner's own words now). Asks the owner for the source before saving anything. Use only when the user explicitly asks.
|
|
4
4
|
argument-hint: "<what to add or correct>"
|
|
5
5
|
disable-model-invocation: true
|
|
6
|
-
allowed-tools: AskUserQuestion, mcp__plugin_sphica_record__glean_begin, mcp__plugin_sphica_record__glean_fetch, mcp__plugin_sphica_record__record_context, mcp__plugin_sphica_record__record_check, mcp__plugin_sphica_record__record_save, mcp__plugin_sphica_sphica__search, mcp__plugin_sphica_sphica__read, mcp__plugin_sphica_sphica__status
|
|
6
|
+
allowed-tools: AskUserQuestion, mcp__plugin_sphica_record__glean_begin, mcp__plugin_sphica_record__glean_fetch, mcp__plugin_sphica_record__record_context, mcp__plugin_sphica_record__record_check, mcp__plugin_sphica_record__record_save, mcp__plugin_sphica_record__record_more, mcp__plugin_sphica_sphica__search, mcp__plugin_sphica_sphica__read, mcp__plugin_sphica_sphica__status
|
|
7
7
|
---
|
|
8
8
|
|
|
9
9
|
# glean — add what was found later, with its source
|
|
@@ -38,21 +38,25 @@ owner says there is no source, save it unsourced and say so.
|
|
|
38
38
|
|
|
39
39
|
## Flow
|
|
40
40
|
|
|
41
|
-
Everything goes through Sphica's `record` MCP server (`glean_begin`, `glean_fetch`, `record_context`, `record_check`, `record_save
|
|
41
|
+
Everything goes through Sphica's `record` MCP server (`glean_begin`, `glean_fetch`, `record_context`, `record_check`, `record_save`,
|
|
42
|
+
`record_more`) and the
|
|
42
43
|
read tools `search` and `read`. Pass the repository root as `cwd` to every tool.
|
|
43
44
|
|
|
44
45
|
1. **Find the records** the target concerns with `search`, and `read` each. Note each record's key and `revision` (read prints it)
|
|
45
46
|
2. **Ask for the source** (above). Have the owner state it in this session: the owner's words are captured and become citable
|
|
46
47
|
3. **Begin**: `glean_begin` with this session (`${CLAUDE_SESSION_ID}` in Claude Code; in Codex, `CODEX_THREAD_ID` from your shell). It returns a `run`
|
|
47
|
-
4. **Bring in the source**: for a GitHub issue or pull request URL of this repository, `glean_fetch` with the run and URL; it keeps the text as sources
|
|
48
|
-
and lists their refs
|
|
48
|
+
4. **Bring in the source**: for a GitHub issue or pull request URL of this repository, `glean_fetch` with the run and URL; it keeps the text as sources,
|
|
49
|
+
says how many, and lists their refs with who wrote each (read a source with `read s<id>`; when its reply ends with `call record_more with cursor: "..."`, the rest of the list is read with
|
|
50
|
+
`record_more`; everything is already kept, so never fetch again for it). For a file, cite it in the record (`file`); Sphica reads it from git itself. For anything else (meeting notes, chat), cite
|
|
49
51
|
the owner's message that quotes it
|
|
50
|
-
5. **Read**: `record_context` with the run: the owner's messages in this session with their refs. When a page
|
|
51
|
-
`call record_context with after: "
|
|
52
|
+
5. **Read**: `record_context` with the run: the owner's messages in this session with their refs. When a page's last line says
|
|
53
|
+
`call record_context with after: "..."`, call it again with that `after`, exactly as written, until a page names none
|
|
52
54
|
6. **Check**: `record_check` with the run and the record below. It runs the save in a transaction that rolls back, so it refuses what the
|
|
53
|
-
save would refuse and lists what would change (`would be active`, `would: <change>`) without writing it
|
|
55
|
+
save would refuse and lists what would change (`would be active`, `would: <change>`) without writing it, the verdict and the counts first
|
|
56
|
+
(a reply that ends with `call record_more with cursor: "..."` goes on with `record_more`). Fix errors and check again. A
|
|
54
57
|
note to ask the owner for a source means step 2 is not done
|
|
55
|
-
7. **Save**: `record_save`.
|
|
58
|
+
7. **Save**: `record_save`. A reply that starts with `✗` saved nothing: fix the record, check it, and save with the same run.
|
|
59
|
+
**Report** what changed, copying save's lines (all of them: read on with `record_more` when the reply names a cursor)
|
|
56
60
|
|
|
57
61
|
## The record
|
|
58
62
|
|
package/skills/harvest/SKILL.md
CHANGED
|
@@ -4,7 +4,7 @@ description: Reads one GitHub pull request of the current repository (its body,
|
|
|
4
4
|
argument-hint: "<PR number>"
|
|
5
5
|
disable-model-invocation: true
|
|
6
6
|
context: fork
|
|
7
|
-
allowed-tools: mcp__plugin_sphica_record__harvest_begin, mcp__plugin_sphica_record__record_context, mcp__plugin_sphica_record__record_check, mcp__plugin_sphica_record__record_save, mcp__plugin_sphica_sphica__search, mcp__plugin_sphica_sphica__read, mcp__plugin_sphica_sphica__status
|
|
7
|
+
allowed-tools: mcp__plugin_sphica_record__harvest_begin, mcp__plugin_sphica_record__record_context, mcp__plugin_sphica_record__record_check, mcp__plugin_sphica_record__record_save, mcp__plugin_sphica_record__record_more, mcp__plugin_sphica_sphica__search, mcp__plugin_sphica_sphica__read, mcp__plugin_sphica_sphica__status
|
|
8
8
|
---
|
|
9
9
|
|
|
10
10
|
# harvest — keep what a pull request decided and implemented
|
|
@@ -26,7 +26,7 @@ each record quoting the words it came from.** No template is assumed; decide fro
|
|
|
26
26
|
|
|
27
27
|
## Flow
|
|
28
28
|
|
|
29
|
-
Everything goes through Sphica's `record` MCP server (`harvest_begin`, `record_context`, `record_check`, `record_save`). Pass the repository root
|
|
29
|
+
Everything goes through Sphica's `record` MCP server (`harvest_begin`, `record_context`, `record_check`, `record_save`, `record_more`). Pass the repository root
|
|
30
30
|
as `cwd` to every tool.
|
|
31
31
|
|
|
32
32
|
1. **Pick the pull request**: the number in the target. Without one, do nothing and reply that harvest needs a pull request number
|
|
@@ -35,14 +35,17 @@ as `cwd` to every tool.
|
|
|
35
35
|
3. **Read**: `record_context` with the run. Each source is printed as `## s<N> <kind> <artifact> by <login> (<association>) <time>` followed by
|
|
36
36
|
its text (`, the owner` follows the association for the owner's own account), then the project's live records. `(harvested before)` marks
|
|
37
37
|
sources an earlier harvest already looked at: what they decided may already be saved, so search before recording it again. Read all of it before writing:
|
|
38
|
-
when a page
|
|
38
|
+
when a page's last line says `call record_context with after: "..."`, call it again with that `after`, exactly as written, until a page names none
|
|
39
|
+
(a source too long for a page says where `read` goes on)
|
|
39
40
|
4. **Check**: `record_check` with the run and the record as `record`. The shape and fields are trace's ([../trace/SKILL.md](../trace/SKILL.md),
|
|
40
41
|
"The record"), with `work` left out. Keys are saved as `harvest:<number>/<key>`. As in trace, check runs the save in a transaction that
|
|
41
|
-
rolls back and says what would become of each record (`would be active`, ...)
|
|
42
|
+
rolls back and says what would become of each record (`would be active`, ...), the verdict and the counts first; when a reply ends with
|
|
43
|
+
`call record_more with cursor: "..."`, read the rest with `record_more`. Fix and check again until there are no errors.
|
|
42
44
|
A file the pull request touched may have moved since: on a warning that a path is not in the working tree, give the commit that holds it,
|
|
43
45
|
or anchor where the code is now
|
|
44
|
-
5. **Save**: `record_save` with the same run and record
|
|
45
|
-
|
|
46
|
+
5. **Save**: `record_save` with the same run and record. A reply that starts with `✗` saved nothing: fix the record, check it, and save
|
|
47
|
+
with the same run
|
|
48
|
+
6. **Report** to the owner what was saved, copying save's lines (all of them: read on with `record_more` when the reply names a cursor)
|
|
46
49
|
|
|
47
50
|
## Who adopts
|
|
48
51
|
|
package/skills/trace/SKILL.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
name: trace
|
|
3
3
|
description: Extracts what a coding session decided and implemented (decisions and rejected options, constraints, implementations, findings, dead ends, open questions) into records whose every claim quotes the captured conversation, so a later session can find them. With "pending", lists this project's sessions not traced yet. Use when the user asks, or on your own when Sphica's session-start notice says earlier sessions wait to be traced, after the user's request is done.
|
|
4
4
|
argument-hint: "[pending]"
|
|
5
|
-
allowed-tools: AskUserQuestion, mcp__plugin_sphica_record__trace_pending, mcp__plugin_sphica_record__trace_begin, mcp__plugin_sphica_record__record_context, mcp__plugin_sphica_record__record_check, mcp__plugin_sphica_record__record_save, mcp__plugin_sphica_sphica__search, mcp__plugin_sphica_sphica__read, mcp__plugin_sphica_sphica__status, mcp__plugin_sphica_sphica__fields
|
|
5
|
+
allowed-tools: AskUserQuestion, mcp__plugin_sphica_record__trace_pending, mcp__plugin_sphica_record__trace_begin, mcp__plugin_sphica_record__record_context, mcp__plugin_sphica_record__record_check, mcp__plugin_sphica_record__record_save, mcp__plugin_sphica_record__record_more, mcp__plugin_sphica_sphica__search, mcp__plugin_sphica_sphica__read, mcp__plugin_sphica_sphica__status, mcp__plugin_sphica_sphica__fields
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
# trace — keep what a session decided and implemented
|
|
@@ -28,7 +28,7 @@ replacing the owner's).
|
|
|
28
28
|
## Flow
|
|
29
29
|
|
|
30
30
|
Everything goes through Sphica's `record` MCP server (its tools are `trace_pending`, `trace_begin`, `record_context`, `record_check`,
|
|
31
|
-
`record_save`). Pass the repository root as `cwd` to every tool.
|
|
31
|
+
`record_save`, `record_more`). Pass the repository root as `cwd` to every tool.
|
|
32
32
|
|
|
33
33
|
1. **Pick the session.** Without a target, it is this session: its id is `${CLAUDE_SESSION_ID}` in Claude Code; in Codex, read `CODEX_THREAD_ID`
|
|
34
34
|
from your shell environment. With `pending`, call `trace_pending`, show the owner the list, and ask which to trace (AskUserQuestion in
|
|
@@ -37,17 +37,22 @@ Everything goes through Sphica's `record` MCP server (its tools are `trace_pendi
|
|
|
37
37
|
2. **Begin**: `trace_begin` with that `session`. It returns a `run` id bound to that session and this project; the record never names them
|
|
38
38
|
3. **Read**: `record_context` with the run. It prints each captured message as `## s<N> owner|assistant <turn> <time>` followed by its text,
|
|
39
39
|
the edits observed, and the project's live records. `(traced before)` marks messages an earlier trace already looked at.
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
rest
|
|
40
|
+
It comes in pages: when a page's last line says `call record_context with after: "..."`, call it again with that `after`, exactly as written
|
|
41
|
+
(`s<N>` while messages follow, then `t<id>.<line>` while the edits, fields, and live records go on), until a page names no `after`.
|
|
42
|
+
A message too long for a page ends with `(cut here; read s<N>@<byte> for the rest)`: read on with `read` when what it says matters.
|
|
43
|
+
Saving marks as looked at only the messages you were shown and those you quote; the rest stay pending.
|
|
43
44
|
Use `search` and `read` to look at older records this session may replace
|
|
44
45
|
4. **Check**: `record_check` with the run and the record below as `record`. It runs the save in a transaction that rolls back, so nothing is
|
|
45
46
|
written: it refuses what the save would refuse, and says what would become of each record (`would be active`, `would stay a candidate` with
|
|
46
|
-
the reason, `would be superseded`, `would be quarantined`).
|
|
47
|
+
the reason, `would be superseded`, `would be quarantined`). Its first lines are the verdict and the counts. When a reply ends with
|
|
48
|
+
`call record_more with cursor: "..."`, the rest of its lines are read with `record_more` and that cursor, until a reply names none
|
|
49
|
+
(the same goes for `record_save`; nothing is checked or saved again by reading on). Errors refuse the save; fix and check again. Warnings say what will be
|
|
47
50
|
left out, quarantined, or kept as a candidate, and why. An anchor warning (a path not in the working tree, with near paths; a directory; a
|
|
48
51
|
symbol not in the file) means fix the anchor and check again; keep it only when you know it is right
|
|
49
|
-
5. **Save**: `record_save` with the same run and record. A run saves once
|
|
50
|
-
|
|
52
|
+
5. **Save**: `record_save` with the same run and record. A run saves once. A reply that starts with `✗` saved nothing: fix the record,
|
|
53
|
+
check it, and save with the same run
|
|
54
|
+
6. **Report** to the owner what was saved, copying save's lines (active, candidate with the reason, quarantined, superseded), all of them:
|
|
55
|
+
read on with `record_more` when the reply names a cursor
|
|
51
56
|
|
|
52
57
|
A session with nothing worth keeping is saved with `"units": []`: it is marked as looked at, so pending stops listing it.
|
|
53
58
|
|