Summary

KR-3 ST1 ships the iso_node_* typed-graph tool family — 4 model-facing MCP tools that replace Hermes' flat memory.set / memory.append / memory.get surface with a typed-node API backed by Plan 02's kronicle.agent_scratchpad_entries.

v0.1 simplification per spec § 32: iso_node_* operates only against the scratchpad surface. Full read-across the 17 entity tables lands in KR-3a once read patterns + permissions firm up. The model still gets a richer memory surface than flat MEMORY.md, just scoped to Kora's own scratchpad.

Deferred-write envelopes

Write paths route through scratchpad.write_scratchpad_entry which still raises ScratchpadWriteNotAvailableError (KR-2 ST3 deferral). The tool handlers catch the defer and return a structured envelope:

{
  "ok": false,
  "deferred": true,
  "deviation_id": "D-kr2-st3-no-scratchpad-write-mcp-tool",
  "message": "[kora.isokron.todo] ..."
}

In-band signal to the model rather than an exception escape. When K-8 ships the Sea MCP write tool, write_scratchpad_entry body swaps to the MCP call and these envelopes naturally turn into {"ok": true, "entry_id": "..."} — handler code stays unchanged.

Capability gating

Each handler asserts the relevant cap_* via assert_kora_can_perform (e.g. iso_node_create → cap_write_agent_scratchpad). The Python mirror of TS-side assertKoraCanPerform ships in KR-6 (Constitution pre-screen middleware); until then assert_kora_can_perform is a no-op stub that logs every call tagged with new BUILD_DEVIATIONS entry D-kr3-st1-capability-check-deferred so operators can grep how often the stub is being relied on. Spec § ST1 explicitly pre-authorized this deferral.

v0.1 content encoding

The substrate's kronicle.agent_scratchpad_entries.scratchpad_kind is a closed 7-value enum, separate from the broader 18 IsoKron entity kinds. v0.1 packs node_kind + title into the content_inline header so reads can recover it without schema changes:

iso_node v0.1
node_kind: Decision
title: Pick IsoKron
---
We picked it because ...

The body delimiter (\n---\n) lets the model include arbitrary markdown without breaking the parse. Legacy / non-iso_node entries surface as body-only (no node_kind / title).

What landed

Test plan

22 new tests, all passing:

Schemas + registration (3):

• test_iso_node_schemas_are_well_formed — 4 schemas, OpenAI function-call shape
• test_node_kinds_canonical_list_has_18_entries — 17 IsoKron + KronicleBlock
• test_iso_node_create_schema_enum_matches_node_kinds — JSON Schema enum in sync with Python NODE_KINDS tuple

Content packing (3):

• test_pack_then_unpack_round_trips_fields
• test_unpack_handles_legacy_unpacked_content
• test_unpack_handles_null_content_inline

Capability stub (1):

• test_assert_kora_can_perform_stub_logs_deviation_id — log line carries both the deviation ID + the capability name

iso_node_create (4):

• Returns deferred envelope with the correct deviation_id
• Rejects invalid node_kind
• Rejects invalid scratchpad_kind
• Errors on missing required fields

iso_node_read (3):

• Finds entry in own cache
• Finds entry in cross-agent cache
• Returns error on missing entry

iso_node_search (4):

• Filters by node_kind
• Free-text substring case-insensitive
• Respects server-side limit cap (max 50)
• cross_agent_only includes other actor_kinds (critic, oracle, etc.)

iso_node_supersede (2):

• Inherits node_kind from the original entry — verified by checking the deferred submission actually ran (means lookup succeeded + packing happened before the write defer)
• Errors when original entry can't be resolved

Dispatch (2):

• Unknown tool name in iso_node dispatcher raises
• provider.handle_tool_call routes iso_node_* by prefix

Gates

• ty check — 7,337 diagnostics, zero-delta vs KR-2 ST4 baseline.
• pytest tests/plugins/memory/ — 270/270 passing (22 new ST1 + 248 pre-ST1).
• Full suite via xdist (-n auto): 24,535 / 157 failed / 43 errors / 129 skipped. Same tests/tools/* + tests/tui_gateway/* xdist isolation noise as KR-2 ST2-ST4; the failing kanban tests pass in isolation. None of the failures touch plugins/memory/isokron/.

Rule-6 / BUILD_DEVIATIONS / Open asks

• New deviation D-kr3-st1-capability-check-deferred — closes when KR-6 ships the Python actorHasCapability mirror.
• Existing deviations carry forward: D-kr2-st2-capability-matrix-mirror ← K-7, D-kr2-st3-no-scratchpad-write-mcp-tool ← K-8 (affects iso_node_create + iso_node_supersede writes), D-kr2-st4-no-chain-emit-mcp-tool ← K-9 (affects iso_node_supersede's kora.node.superseded event).
• All four deviations follow the same shape: signature is forward-stable, body swaps from raise <DeferredError> to mcp_client.invoke(...). Tool handlers stay unchanged.

Standing by for KR-3 ST2 dispatch (iso_link_* family — typed edges; ST2 recon on RelationLink table name + schema).

🤖 Generated with Claude Code