Skip to content
This repository was archived by the owner on May 26, 2026. It is now read-only.

KR-2 ST1: IsoKronMemoryProvider skeleton + connection plumbing#5

Merged
rafe-walker merged 1 commit into
mainfrom
feat/kora-KR2-provider-skeleton
May 20, 2026
Merged

KR-2 ST1: IsoKronMemoryProvider skeleton + connection plumbing#5
rafe-walker merged 1 commit into
mainfrom
feat/kora-KR2-provider-skeleton

Conversation

@rafe-walker

Copy link
Copy Markdown
Owner

Bucket: KR-2 sub-task 1 / 4. Branch: feat/kora-KR2-provider-skeleton @ 3e90e58.

Summary

The architectural unlock for Kora's memory. Ships the structural skeleton of plugins/memory/isokron/ — a MemoryProvider subclass that will replace Hermes' flat MEMORY.md/USER.md once ST2-ST4 fill in the real reads + writes against the IsoKron substrate.

Diff: 9 files added/modified, +1,241 lines.

Architecture (PM lean accepted, no Rule-3 ASK)

  • Reads → asyncpg pool, direct Postgres on IsoKron substrate (Role Charter, capability matrix, policy registry, scratchpad, event_log)
  • Writes → MCP client to Sea MCP server (kora__* tool surface, authorization + Constitution pre-screen + chain audit substrate-side)
  • No direct DB writes anywhere — structural invariant enforced by NotImplementedError on every write path until ST3 wires the MCP client.

Diagram + full architecture in plugins/memory/isokron/README.md.

What ST1 delivers

File Role
plugins/memory/isokron/init.py register(ctx) + env-var ${VAR} expansion + config loader from plugins.entries.isokron
plugins/memory/isokron/provider.py IsoKronMemoryProvider — 4 required ABC methods implemented; 12 optional hooks raise NotImplementedError with [kora.isokron.todo] Rule-6 messages
plugins/memory/isokron/connection.py IsoKronConnection + dedicated-thread asyncio loop (matches tools/mcp_tool.py upstream pattern). pg_pool() / mcp_client() raise until ST2/ST3
plugins/memory/isokron/config.py pydantic v2 IsoKronProviderConfig — DSN scheme check, MCP transport check, cache_ttl_seconds bounds, extra="forbid". ISOKRON_CONFIG_SCHEMA for kora memory setup
plugins/memory/isokron/plugin.yaml manifest: name, version 0.1.0, pip_dependencies (asyncpg, mcp, blake3), hooks
plugins/memory/isokron/README.md architecture diagram (hybrid reads/writes), config example, KR-2 ST1-ST4 surface table, operator pitfalls
tests/plugins/memory/test_isokron_provider_skeleton.py 29 tests, all pass serially in 0.80s
pyproject.toml new [project.optional-dependencies].isokron: asyncpg==0.31.0, mcp==1.26.0, blake3==1.0.7
uv.lock regenerated

Verification

  • 29 ST1 smokes pass serially (0.80s).
  • discover_memory_providers() finds isokron at position 5/9 with manifest description.
  • ty check: 7,341 diagnostics — identical to baseline. Zero new diagnostics.
  • Full suite (xdist): 24,503 passed / 152 failed / 129 skipped (203.42s). Delta vs KR-1 ST4: +32 passed (29 new + 3 parametric variance), −3 failed (xdist noise). No new real failures.

Test layout note (not a Rule-3 deviation)

Bucket spec said plugins/memory/isokron/__tests__/test_provider_skeleton.py; repo convention is tests/plugins/memory/test_<name>_provider.py. Followed repo convention because pytest auto-discovers there; the bucket's tests/ path is JS convention, not Python. Cosmetic adaptation, no Rule-3 ASK needed.

Rule-6 honest labels

  • README §"Operator pitfalls" prominently flags: memory.provider: isokron will half-work today — provider registers + initializes, but every call to prefetch/sync_turn/system_prompt_block raises NotImplementedError. Keep Hermes-inherited default (flat MEMORY.md) until ST2 lands.
  • NotImplementedError messages all tagged [kora.isokron.todo] + name the sub-task that lands the real impl.
  • Connection wrapper docstring: "KR-2 ST1's connection wrapper does NOT open any real network connections."

STOP-gate

Architecture STOP-gate cleared: tools/mcp_tool.py exposes a clean Python MCP client surface. ST3 will wire the write path on top — no Rule-3 ASK.

🤖 Generated with Claude Code

The architectural unlock for Kora's memory. Ships the structural
skeleton of plugins/memory/isokron/ — a MemoryProvider subclass that
will replace Hermes' flat MEMORY.md/USER.md once ST2-ST4 fill in
reads + writes against the IsoKron substrate.

Architecture decision (PM lean accepted, no Rule-3 ASK):
* Reads → asyncpg pool, direct Postgres on IsoKron substrate
* Writes → MCP client to Sea MCP server (authorization + audit)
* No direct DB writes anywhere in this provider — structural
  invariant enforced by raising NotImplementedError on every write
  path until ST3 wires the MCP client.

Files added:
* plugins/memory/isokron/__init__.py — register(ctx) + env-var
  expansion + config loader from plugins.entries.isokron
* plugins/memory/isokron/provider.py — IsoKronMemoryProvider class.
  Required ABC methods implemented (name, is_available, initialize,
  get_tool_schemas). All 12 optional hooks override the ABC defaults
  to raise NotImplementedError with a "[kora.isokron.todo]" Rule-6
  message so operators can grep their logs.
* plugins/memory/isokron/connection.py — IsoKronConnection wrapper.
  Dedicated-thread asyncio loop (matches tools/mcp_tool.py upstream
  pattern). pg_pool() and mcp_client() accessors raise until ST2/ST3.
* plugins/memory/isokron/config.py — pydantic v2 IsoKronProviderConfig
  with field-level validation: postgres:// DSN scheme check, MCP
  endpoint stdio/http(s) transport check, 0 <= cache_ttl_seconds
  <= 3600, extra="forbid" for typo detection. Plus
  ISOKRON_CONFIG_SCHEMA for kora memory setup.
* plugins/memory/isokron/plugin.yaml — manifest with pip deps + hooks
* plugins/memory/isokron/README.md — architecture diagram (hybrid
  reads/writes), config example, KR-2 ST1-ST4 surface table,
  operator pitfalls
* tests/plugins/memory/test_isokron_provider_skeleton.py — 29 tests:
  plugin discovery + register, construct + lifecycle, config
  validation (5 negative tests + env-var expansion), 12 stub-method
  Rule-6 message verifications, static metadata, connection
  accessor NotImplementedError checks.

Files modified:
* pyproject.toml — new [project.optional-dependencies].isokron
  extra: asyncpg==0.31.0, mcp==1.26.0, blake3==1.0.7 (blake3 needed
  for ST3 scratchpad content_hash verification).
* uv.lock — regenerated for the new extra.

Test layout adapted (NOT a Rule-3 deviation): bucket said
`plugins/memory/isokron/__tests__/test_provider_skeleton.py`, repo
convention is `tests/plugins/memory/test_<name>_provider.py`. I
followed the repo convention because pytest auto-discovers there;
the bucket's `__tests__/` path is JavaScript convention, not Python.

Architecture STOP-gate cleared (per ST1 spec): the MCP client
surface in upstream Hermes (tools/mcp_tool.py) exposes a clean
Python client. No Rule-3 ASK needed; ST3 will wire the MCP write
path on top.

Verification:
* 29 ST1 smokes pass serially in 0.80s.
* `from plugins.memory import discover_memory_providers` finds
  isokron at position 5 of 9 with the manifest description.
* ty check: 7,341 diagnostics — identical to ST1/ST2/ST3/ST4
  baseline. Zero new diagnostics from KR-2 ST1.
* Full suite (xdist parallel) — running in background, will be
  appended to PR description.

Rule-6 honest labels: ST1 ships the skeleton, NOT a working
provider. `memory.provider: isokron` in config.yaml will half-work
today — provider registers + initializes, but every call to
prefetch/sync_turn/system_prompt_block raises NotImplementedError.
Operators should keep the Hermes-inherited default (flat MEMORY.md)
until ST2 lands.

Bucket: KR-2 sub-task 1 / 4. Architecture decision documented in
plugins/memory/isokron/README.md §"Architecture (hybrid, PM-leaned)".

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@rafe-walker rafe-walker merged commit f129dca into main May 20, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant