kepos-hindsight

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.

What it does

• Runs raw Hindsight recall on every direct user turn, with the current message
  and a small amount of prior user context.
• Injects one Hindsight context on every direct turn: the host's current local
  time is authoritative, while recalled facts remain explicitly untrusted
  historical context. Retrieval failures time out and never block a reply.
• Retains into one stable Hindsight document per session: 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.
• Exposes one deliberate read-only tool: 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.

Why not use the official coding-agent integration?

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:

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.

Bank strategies and prompts

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.

Install as a local DSH bundle

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

Configuration

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.

Yuki lives in DSH live config

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.

Development

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.

Maintainer releases

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.

First-time npm and GitHub setup

Before the first trusted release, a maintainer must:

1. 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.

2. In npm package settings, add a Trusted Publisher for the LamplitIsles
   GitHub owner, repository kepos-hindsight, workflow
   .github/workflows/release.yml, and environment npm.
3. Create the protected GitHub npm environment and apply the repository's
   release approval policy (for example, required reviewers and the allowed
   release tags).

4. 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.

Routine release

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

Design and operating notes

The companion-memory notes cover
the coding/companion boundary, prompt and extraction policy, session backfill,
cold-start cost, reranking, provider migration, and related integrations.