@lamplitisles/kepos-hindsight
用于 Hindsight 的小型 DSH 伴侣记忆适配器
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:LamplitIsles/kepos-hindsight#f796c0dad64e7eda1f5e6e83d519493716f38e8eKepos Hindsight 以 @lamplitisles/kepos-hindsight 发布，当前版本为 0.1.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
A small Hindsight adapter for a
companion-style DSH agent. It replaces only DSH's official coding-agent
adapter. Codex can keep using the official coding-agent hooks and the same
~/.hindsight/coding-agent.json file.
The package targets the exact DSH 0.1.2-rc.1 Host and Web client contract;
use a matching rc.1 DSH runtime when installing it as a bundle.
dsh:<session-id>.
The first completed turn after DSH starts replaces it with the full available
session transcript; later turns append only their JSONL delta.hindsight_reflect, for bank-defined
synthesis across multiple memories when the automatically supplied raw facts
and current conversation cannot answer the question.It does not seed a codebase, create knowledge pages, auto-reflect, import a bank template, or enable subagents.
The official integration treats a repository or worktree as the durable thing: it surveys code, retains coding sessions, maintains knowledge pages, recalls past decisions, and exposes project-oriented tools. That is a good fit for an engineering agent, but it is the wrong identity and lifecycle for one companion continuing across unrelated conversations and workspaces.
This adapter changes the product contract rather than merely changing a prompt:
| Concern | Official coding-agent integration | This companion adapter |
|---|---|---|
| Durable identity | Repository/workspace | One user-selected relationship bank |
| Automatic retrieval | Coding knowledge, initial synthesis, and page guidance | Raw, non-LLM recall before every direct user turn |
| Repetition | Coding lifecycle decides when synthesis/guidance is useful | Every result remains eligible on every relevant turn; no cross-turn suppression |
| Retention | Coding sessions, repository facts, Git/doc strategies | Clean user/assistant dialogue in one repairable document per chat session |
| Reflect | Part of the coding knowledge workflow | Deliberate explicit tool for questions that need synthesis |
| Tools | Knowledge pages, project search/capture/ingest, Reflect | One read-only hindsight_reflect tool |
| Routing | Workspace-derived banks | Workspace, CWD, and preset never reroute the selected bank |
| Policy ownership | Ships coding missions and strategies | Sends no strategy or mission; the bank owner defines companion memory policy |
| Agent topology | Supports coding-agent and subagent workflows | Direct companion sessions only; subagents are excluded |
The practical result is continuity without coding-agent overhead: inexpensive retrieval runs each turn, the full source dialogue is submitted as a stable session document, and expensive Reflect synthesis happens only when requested.
See Companion memory design for the lifecycle, failure semantics, prompt boundary, and the design principles behind these choices.
The adapter has no opinion about the bank's retain_mission,
observations_mission, or reflect_mission.
It never calls /import, does not send a Hindsight strategy, and does not
send a retain context. Configure those missions in Hindsight for the target
bank, through its normal UI or bank-config API. This keeps each companion's
memory policy entirely user-owned and prevents a DSH plugin update from
overwriting it.
The short wrapper around recalled facts is a prompt-injection boundary, not a Hindsight strategy: recalled history is evidence, never an instruction. The clock is generated locally for the current turn, travels in the same context, and is excluded from the retained transcript.
pnpm install
pnpm build
dsh plugin --profile web add file:/absolute/path/to/kepos-hindsight
The bundle mounts kepos-hindsight. It does not alter the official Codex
integration. Confirm the composition before starting DSH:
dsh --profile web --dump-config
The output should include an enabled kepos-hindsight row. A running DSH host
must be restarted after changing its bundle list.
For a published release, install the public package directly:
dsh plugin --profile web add @lamplitisles/kepos-hindsight
Endpoint, credentials, per-bank missions, and the global disabled flag stay
in the normal shared Hindsight config, ~/.hindsight/coding-agent.json.
Choose the DSH companion bank at Settings → Plugins → Hindsight memory.
It defaults to yuki-memory. This is the only routing choice: a
DSH agent, its preset, its workspace, and the current working directory never
select or remap the bank. The chosen bank is used by automatic recall,
asynchronous retain, and hindsight_reflect alike.
Saving is a live DSH setting and applies on the next turn. DSH intentionally allows Settings RPC writes only from its loopback Web UI, so change it on the host rather than through a Kepos-proxied mobile connection.
The optional harnesses.dsh.companion.recall extension tunes retrieval only;
it does not choose a bank or add a recall/retain switch. The official
coding-agent adapter ignores this extension.
{
"harnesses": {
"dsh": {
"companion": {
"recall": {
"budget": "low",
"maxTokens": 900,
"types": ["observation", "world", "experience"],
"preferObservations": true,
"topK": 3,
"contextTurns": 2,
"maxQueryChars": 800,
"timeoutMs": 4000
}
}
}
}
}
This example is optional: the values shown are the defaults. low recall is
retrieval rather than a Reflect LLM request. Raise its budget only after
checking that a real conversation needs broader retrieval. Automatic recall
and retain deliberately have no UI controls; the global Hindsight disabled
and retainSessions settings remain their shared service-level safeguards.
This repository deliberately ships no Yuki persona or preset. Create and keep
the preset locally under $DSH_HOME/.agent-presets/yuki/, preferably by copying
DSH's current standard preset through DSH's preset UI and then editing the
copy. Disable or remove its delegation group for a single-session companion. The
workspace's own AGENTS.md, SOUL.md, IDENTITY.md, and USER.md remain the
source of truth for personality and relationship behavior.
pnpm check
pnpm test
pnpm build
The tests use fake Hindsight HTTP responses and test-owned temporary config directories; they never read or modify a live bank.
The release workflow publishes @lamplitisles/kepos-hindsight only for a
semantic-version tag matching v<semver>. It verifies a frozen pnpm install,
typecheck, tests, build, release preflight, and the packed DSH artifact before
the publish job can run.
Before the first trusted release, a maintainer must:
Create or claim the @lamplitisles npm scope. Temporarily set the package
version to the distinct bootstrap prerelease 0.1.0-beta.0 (do not create
a Git release tag), then run the matching preflight and checks:
pnpm check
pnpm test
pnpm build
GITHUB_REF_NAME=v0.1.0-beta.0 pnpm release:check
pnpm pack-smoke
While authenticated interactively on the maintainer machine, publish that bootstrap version to npm's beta channel:
npm publish --access public --tag beta
This leaves 0.1.0 available for the first stable OIDC release.
In npm package settings, add a Trusted Publisher for the LamplitIsles
GitHub owner, repository kepos-hindsight, workflow
.github/workflows/release.yml, and environment npm.
Create the protected GitHub npm environment and apply the repository's
release approval policy (for example, required reviewers and the allowed
release tags).
Create the first stable release through the authorized forge command. CI synchronizes its disposable package manifest from the tag before preflight and publication:
og tag v0.1.0
The tag starts the OIDC-backed workflow, which publishes 0.1.0 to npm's
latest channel. Do not use a direct Git tag or push command.
Trusted Publishing uses GitHub's OIDC identity and npm provenance. Do not add an npm authentication token or any other npm credential to this repository or its GitHub secrets.
Create and publish a tag after the change is ready with the repository-authorized forge command:
og tag v0.1.0
Use a prerelease such as v0.1.1-beta.1 for beta testing. Stable tags publish
to npm's latest dist-tag; tags containing a prerelease identifier publish to
beta. CI synchronizes the package version to the tag in its disposable
verification workspace, then publishes only the verified artifact.
To reproduce the release preflight locally without publishing, use a disposable working tree, synchronize its package manifest from the tag, then run the check:
GITHUB_REF_NAME=v0.1.0 pnpm release:sync-version
GITHUB_REF_NAME=v0.1.0 pnpm release:check
The preflight rejects malformed or mismatched tags, non-public npm metadata, and packed artifacts that omit the DSH entry points or include unsafe build output. The full local verification remains:
pnpm install --frozen-lockfile
pnpm check
pnpm test
pnpm build
pnpm pack-smoke
The companion-memory notes cover the coding/companion boundary, prompt and extraction policy, session backfill, cold-start cost, reranking, provider migration, and related integrations.