sphica 0.6.49 → 0.6.51
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/dist/deliver.js +1 -3
- package/dist/mcp-record.js +661 -169
- package/dist/mcp.js +1169 -1142
- package/package.json +1 -1
- package/skills/forget/SKILL.md +9 -4
- package/skills/glean/SKILL.md +13 -9
- package/skills/harvest/SKILL.md +10 -7
- package/skills/trace/SKILL.md +26 -11
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "sphica",
|
|
3
|
-
"version": "0.6.
|
|
3
|
+
"version": "0.6.51",
|
|
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/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
|
|
|
@@ -86,7 +90,7 @@ Japanese corner brackets, backticks, apostrophes): quote more of the owner's own
|
|
|
86
90
|
Check reads where the words sit, not what they mean: whether they settle this record is yours to judge.
|
|
87
91
|
|
|
88
92
|
Every op carries the `revision` read printed; a record changed since is refused, so read it again. To correct what a record says, write a new
|
|
89
|
-
record in `units` (trace's shape
|
|
93
|
+
record in `units` (trace's shape without the keys `"work"`, `"answers"`, `"field_defs"`, and `"fields"`, and without evidence of the role `decides`, all of which only a trace takes; keys saved as `glean:<key>`) with `supersedes` naming the old one (citing the owner's words, a maintainer's, or the owner's session, not other people's text: words that are in the source, and not only a
|
|
90
94
|
quotation there); records are never rewritten.
|
|
91
95
|
|
|
92
96
|
## When a source turns up for an unsourced record
|
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
|
-
"The record"),
|
|
41
|
-
rolls back and says what would become of each record (`would be active`, ...)
|
|
41
|
+
"The record"), without the keys `"work"`, `"answers"`, `"field_defs"`, and `"fields"`, and without evidence of the role `decides`: only a trace takes those. Keys are saved as `harvest:<number>/<key>`. As in trace, check runs the save in a transaction that
|
|
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
|
|
@@ -36,18 +36,23 @@ Everything goes through Sphica's `record` MCP server (its tools are `trace_pendi
|
|
|
36
36
|
them, but they can still be traced. Trace one session at a time
|
|
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
|
-
the edits observed, and the project's live records. `(traced before)` marks messages an earlier trace already looked at.
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
rest
|
|
39
|
+
the edits observed, the work items there are, and the project's live records. `(traced before)` marks messages an earlier trace already looked at.
|
|
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, work items, 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
|
|
|
@@ -86,10 +91,15 @@ When Sphica's session-start notice in Claude Code says earlier sessions wait to
|
|
|
86
91
|
"aliases": ["database", "storage", "SQLite", "Postgres", "server", "persistence", "..."]
|
|
87
92
|
}
|
|
88
93
|
],
|
|
89
|
-
"work":
|
|
94
|
+
"work": [
|
|
95
|
+
{ "key": "storage", "current": "Decided", "next": [], "status": "done" },
|
|
96
|
+
{ "key": "csv-export", "title": "Rework the export", "goal": "Notes never leave in a CSV", "current": "Not started", "next": ["List the columns"], "status": "active" }
|
|
97
|
+
]
|
|
90
98
|
}
|
|
91
99
|
```
|
|
92
100
|
|
|
101
|
+
In this example `storage` is a work item context already lists, so only what changed is given; `csv-export` is new and gives every field.
|
|
102
|
+
|
|
93
103
|
<!-- english-exempt: the aliases example has to show Japanese words -->
|
|
94
104
|
The `"..."` stands for the other language's words: in this example, `"データベース", "保存先", "DB サーバー", "永続化"`.
|
|
95
105
|
|
|
@@ -106,12 +116,17 @@ The `"..."` stands for the other language's words: in this example, `"データ
|
|
|
106
116
|
| `aliases` | 8 to 12 short search words in **both Japanese and English** a later reader might type: synonyms, the other language's words, abbreviations. Search only; never evidence. Not broad words that match everything (`code`, `fix`, `update`) |
|
|
107
117
|
| `supersedes` | The key of a live record this one replaces (context lists them). The old one is marked superseded, never deleted |
|
|
108
118
|
| `conflicts` | Keys of live records this one contradicts without replacing them. Until resolved, both are held back from automatic injection, except the owner's decision, which only another record the owner adopted holds back |
|
|
109
|
-
| `
|
|
119
|
+
| `answers` | Keys of open questions (context lists them) this record answers, up to 5. Each is closed, withdrawn with this record named as the reason, once this record is active; a decision or constraint also needs the owner's or a maintainer's adoption, so an AI's own decision closes none. Only for a record that settles the question, never a proposal or something merely related. A closed question does not come back: save a new question if it is still open. Not on a question: one question replaces another with `supersedes` |
|
|
120
|
+
| `work` | Work items, optional: one, or a list of up to 10. Context lists the ones there are. For work it lists, reuse its `key` and give only the fields that change (`title`, `goal`, `current`, `next`, `status`): a field left out keeps what is saved, and `next: []` clears the next steps. A new key gives `title`, `goal`, `current`, and `status`. Finished work is `done`; work given up, or opened twice under two keys, is `abandoned`. Change only what the conversation shows: a similar title is no reason to close an item or fold two together. Save says what became of each: created, updated, confirmed with nothing changed, or left as it is because a newer session's trace already wrote it |
|
|
110
121
|
| `field_defs` | Top level, beside `units`. Only when the owner said in this session to keep a field on records: `name` (a lowercase letter, then lowercase letters, digits, `_`; at most 40), `type` (`text`, `enum`, `integer`, `date`), `label`, `description`, `enum` (1 to 30 distinct allowed values, only for `enum`), `kinds` (the unit kinds it applies to; empty means every kind), and `quote` of **the owner's** words defining it (their own, not a quotation inside their message). A field context already lists cannot be defined again |
|
|
111
122
|
| `fields` | On a unit, only for fields context lists or this record's `field_defs` defines: `name`, `value`, and `quote` of the words that say it. The value must be written in the quote as it is: an `integer` whole (not the `95` of `p95`, not the `1` of `1.5` or `1,000`; `1,000` is `1000`), a `date` as `YYYY-MM-DD`, an `enum` value exactly, and a date or enum value on its own (not the `no` of `not`). When no message says the value, leave the field out; never infer one |
|
|
112
123
|
|
|
113
124
|
A field value that breaks these rules refuses the whole save, like a `reconsider_quote` not found: fix it or leave the field out.
|
|
114
125
|
|
|
126
|
+
When check or save refuses `answers` as an unknown key, a `work` list as not an object, or a work item whose key is already there for leaving
|
|
127
|
+
out a field, the record server is older than this Skill. Do not drop them and save without: ask the owner to reload it (`/reload-plugins` in Claude Code; reopen Codex), then
|
|
128
|
+
begin again, read context, and save.
|
|
129
|
+
|
|
115
130
|
What becomes active: a decision or constraint with evidence and adoption (the owner's words, or the AI's own decision under the rules below); an implementation with code or commit evidence
|
|
116
131
|
(an `evidence` anchor on a path this session edited counts); a finding, dead end, or question with evidence. Everything else stays a candidate,
|
|
117
132
|
and a record whose quote is not in the message is quarantined. Neither is injected into later sessions.
|