Session Wiki v0.2

简体中文 | English

Session Wiki is a small semantic sidecar for agent conversations. Its job is to preserve the facts that are easiest to lose during context compaction: active goals, hard constraints, decisions, failed attempts, environment findings, file roles, open threads, and evidence references back to the host transcript.

The v0.2 design is intentionally not a transcript mirror. Codex, Claude Code, or another host agent owns its transcript. Session Wiki only keeps a per-conversation wiki keyed by the host session ID.

Each host conversation gets its own wiki:

<store-root>/
  sessions/
    <host-session-id>/
      session.json
      wiki/
        index.md
        current-state.md
        constraints.md
        decisions.md
        failed-attempts.md
        findings.md
        files.md
        open-threads.md
        evidence-map.md

By default the store root is project-local:

• CLI commands use <current-working-directory>/.session-wiki.
• Host hooks use <host-cwd>/.session-wiki when the hook payload provides a project/workspace cwd.

You can override it with --root <dir> or SESSION_WIKI_HOME when you intentionally want a custom or global store.

Because the default store is runtime state inside the connected project, add .session-wiki/ to that project's .gitignore.

Inside a store root, the wiki is keyed by host session ID rather than a single project-level file:

• Resume the same host conversation in the same store root -> reuse the same wiki.
• Start a new host conversation in the same project -> create a new wiki.
• Work on the same project from two host sessions -> two isolated wikis under that project's .session-wiki.

session.json is control metadata only:

• host type, such as codex, claude-code, or another adapter name;
• host session ID;
• transcript URI/reference owned by the host;
• processed cursor, such as a byte offset into the host transcript;
• wiki revision and hash;
• created/updated timestamps and status;
• feature flags for optional recovery behavior.

Example:

{
  "schema_version": 2,
  "host": {
    "type": "claude-code",
    "session_id": "abc123",
    "transcript_uri": "file:///path/to/host-transcript.jsonl",
    "cwd": "/path/to/project"
  },
  "source_cursor": {
    "kind": "byte_offset",
    "value": 184230
  },
  "wiki_revision": 17,
  "features": {
    "bootstrap": false,
    "recovery_patch": false
  }
}

It does not contain raw chat history.

Create a wiki for a host conversation:

node src/cli.ts init \
  --host claude-code \
  --session abc123 \
  --transcript-uri file:///path/to/host-transcript.jsonl

Apply a temporary host delta without saving the input:

node src/cli.ts update --session abc123 --delta -

Query the wiki on demand:

node src/cli.ts query --session abc123 "why did the previous attempt fail?"

Inspect status:

node src/cli.ts status --session abc123 --json

Removed from v0.2:

• ingest
• raw-transcript.jsonl
• fixed project-level .agent-session
• persistent .session-memory.md
• persistent compact-view.md

update --delta <file|-> accepts JSON, JSON arrays, or JSONL. The input is read, folded into wiki pages, and discarded.

Example event:

{
  "type": "decision",
  "decision": "Use host session ID as the isolation boundary.",
  "reason": "The same project may have multiple independent agent conversations.",
  "priority": "must_preserve"
}

Supported semantic event types include:

• user_message
• assistant_message
• constraint
• decision
• failure
• finding
• state
• open_thread
• tool_call
• tool_result
• test_result
• file_diff

Events can include evidence_ref. If omitted, Session Wiki records a host-scoped reference like host:claude-code:abc123:event-id.

By default Session Wiki is quiet. It updates and answers queries, but does not intervene in native compaction.

Two runtime helpers exist for weaker compaction environments:

node src/cli.ts render-bootstrap --session abc123
node src/cli.ts check-coverage --session abc123 --summary compact-summary.md
node src/cli.ts recover --session abc123 --summary compact-summary.md

They are disabled unless the session was initialized with:

--enable-bootstrap
--enable-recovery-patch

You can pass --force for manual diagnostics. These commands print runtime output; they do not create bootstrap.md or recovery-patch.md.

The Claude adapter reads hook JSON from stdin, uses session_id as the wiki boundary, and reads new bytes from transcript_path using the stored cursor. It never copies the transcript into the wiki store.

Install or link the package, then use session-wiki-claude-hook in Claude Code settings. A starting point is in integrations/claude-code/settings.example.json.

If bootstrap is enabled for the session, a Claude SessionStart event whose source is compact can receive generated additionalContext. This stays off by default.

Codex integration is deliberately conservative until the local hook payload shape is confirmed.

Start with:

SESSION_WIKI_CODEX_PROBE_LOG=/tmp/session-wiki-codex-probe.jsonl session-wiki-codex-probe

The probe records sanitized payload shape only, replacing strings with length markers. After confirming the session and transcript fields, switch to:

session-wiki-codex-hook

The Codex hook updates the wiki best-effort and does not inject recovery context by default.

See integrations/codex/hooks.example.json.

Run tests:

npm test

Run the fixture flow:

npm run fixture