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
Conversation
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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)
Diagram + full architecture in plugins/memory/isokron/README.md.
What ST1 delivers
Verification
Test layout note (not a Rule-3 deviation)
Bucket spec said
plugins/memory/isokron/__tests__/test_provider_skeleton.py; repo convention istests/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
[kora.isokron.todo]+ name the sub-task that lands the real impl.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