Skip to content

One knowledge base for both assistants of an image, kept through spear --build - #29

Merged
daniel-rossier merged 2 commits into
mainfrom
claude-shared-knowledge
Nov 21, 2026
Merged

daniel-rossier merged 2 commits into
mainfrom
claude-shared-knowledge

Conversation

@daniel-rossier

Copy link
Copy Markdown
Contributor

In an image, Claude Code started from the rules of rules.d and the skills only, and searched the index when it chose to. A SPEAR turn starts from more and does not leave retrieval to the model. This brings the two to the same base, and makes what a user adds survive into the image built from their state.

Same base, same way

What a SPEAR request starts from How Claude Code gets it
rules of rules.d, learned rules, the corpus's map, project identity, build and test commands rule files in ~/.claude/rules
skills in scope ~/.claude/skills
passages retrieved from the index for the request a UserPromptSubmit hook, on every prompt; search_corpus goes further
the workspace's recorded knowledge the same hook; spear-knowledge lists and proposes
  • The hook is declared by the image (/etc/claude-code/managed-settings.json), so it runs for the CLI and for an editor extension attached to the container alike.
  • The session's MCP server answers the hook on a private socket, so the embedder is loaded once (0.1 s per prompt once warm, 8 s for the first).
  • The output is kept under the 10 000 characters Claude Code reads in full: knowledge first, then the passages that fit.
  • spear-claude-setup prepares the home; the shell runs it at its start, the claude command before starting.

What a user learns reaches the next image

  • A skill saved in a container was written to the image's library, which the user cannot write; it now goes to the state directory, layered over the shipped library.
  • spear --build adds the saved skills and the learned rules to the registry, index and knowledge it already took.
  • spear --build no longer copies every file of the index and common state into the new layer (it changed their mode): 79 s instead of more than ten minutes on a 29 GB image, and the image no longer doubles.

Checked in containers: a user learns a rule, a skill and a fact, builds an image; a colleague on that image, from another home, gets all three plus the retrieved context in a real Claude Code session started without the wrapper, as an editor extension starts it. The extension's panel itself was not driven.

4542 tests pass.

In an image, the second assistant started from the rules of rules.d and
the skills only, and searched the index when it chose to. A SPEAR turn
starts from more, and does not leave retrieval to the model.

The export now also lays out, as rule files, the rules learned on the
machine, the corpus's map (the tree's own, else the shipped one) and
what the project declares: identity, build and test commands. A guide
rule says what arrives with a request and names the tools.

A hook on every prompt prints the passages retrieved from the index and
the workspace's recorded knowledge, through the functions a turn uses.
The session's MCP server answers it on a private socket, so the embedder
is loaded once; without a server the hook does the work itself.

spear-knowledge becomes a program of the container, reading and
proposing in the store SPEAR uses.
The hook that gives a prompt its retrieved passages and the workspace's
knowledge is now declared by the image itself, so the second assistant
gets it however it is started, from a terminal or from an editor
attached to the container. One server per user answers it; it takes the
corpus from the directory of the request. What it prints stays under
the size that is read in full: knowledge first, then the passages that
fit.

Preparing the home (rules, skills, the index's server) is a command of
its own, run by the shell at its start as well as by the launcher, and
the container gets a name that says what it is.

In a container a saved skill was written into the image's library,
which the user cannot write: it now goes to the state directory, over
the shipped library. Building an image from the state adds the saved
skills and the learned rules to the registry, index and knowledge it
already took.

That build changed the mode of every file of the index and of the
common state, which copied all of them into the new layer; only a file
that lacks the mode is touched now.
@daniel-rossier
daniel-rossier merged commit c702274 into main Nov 21, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant