MemKraft

MemKraft 3.3.0 introduces the Execution State Kernel and the MemKraft Execution Protocol (MKEP/0). The core functionality is distributed across several key modules:

• execution_state.py: Provides ExecutionStateMixin for validation, appending records, managing event sequences, and handling leases.
• execution_projection.py: A pure function project(records, now) that uses a single _TRANSITIONS dictionary to derive state.
• execution_handoff.py: Manages declaring, transitioning, exporting, and importing execution states, including a fail-closed redaction lint.
• execution_protocol.py: Handles mkcjson encoding, digests, envelopes, error registries, and the closed dispatcher.
• execution_cli.py: Provides CLI commands via memkraft exec call and memkraft exec state.
• context_compiler.py: Implements dual opt-in for goal_id and execution_budget.
• mcp.py: Provides 2 read-only tools with structured JSON encoding.

MemKraft follows strict principles to ensure data integrity during version transitions:

1. Three-Step Workflow: Every migration must follow the sequence: dry-run $\rightarrow$ apply $\rightarrow$ rollback. An apply without a dry-run or a rollback path is not permitted.
2. User Markdown is Immutable: Migrations only affect the .memkraft/ sidecar and derived caches. User-provided markdown files (e.g., in memory/) are never rewritten or moved.
3. Derived Caches are Disposable: Regenerable caches (like compiled_truth.jsonl) are not migrated; if a format changes, they are deleted and recreated.
4. No Implicit Migrations: Disk formats are never changed silently by library imports or search calls. Changes only occur via memkraft migrate --apply.
5. N-1 Read Compatibility: Readers are designed to be tolerant of one version prior (e.g., a 2.13 reader can read legacy records without envelopes). Writers always use the latest schema.

The Project Memory Compiler is designed around a strict semantic contract to ensure memory integrity and provenance. Key semantic concepts include:

• Canonical IDs: Framed using SHA-256.
• Temporal Semantics: Uses as_of timestamps and RFC3339 parsing.
• Provenance: Every statement requires source or provenance. All source bytes are bound to receipts.
• Conflict Handling: The system enforces zero silent conflict loss. Every source contradiction must produce either a retained conflict group or a visible aggregate omission diagnostic.
• Authority & Privacy: Uses authority rank-only rules and privacy order/ceiling to manage access and visibility.
• Determinism: The semantic digest is independent of input order, format, or the as_of time (permutation testing ensures input order does not change semantic output).
• Safety: Enforces resource caps, path containment, and prevents symlink escapes via read-only adapters.

MemKraft 4.0 is designed as a substrate for self-evolving agents. The core design principle is that the system turns agent experience into evidence-backed, versioned, and reversible improvements, while strictly keeping execution and authority outside the memory substrate.

To ensure safety and reliability, the 4.0 contract follows these constraints:

• No direct execution: No MemKraft API can execute commands, deploy artifacts, schedule work, or grant permissions.
• Authority separation: Model-generated fields cannot set authority_verified=true. All promotions require explicit authority.
• Data safety: Secrets and artifact bodies are never stored in the ledger. Unauthorized profile/shared scope access fails before any append operation.
• Deterministic projections: Every projection must be deterministic after JSONL line reordering.
• Idempotency: All operations must be idempotent; mismatched retries must fail closed.

MemKraft v2.1 introduces a namespaced directory structure to support multi-agent shared memory and private workspaces. The storage is organized into a .memkraft/ metadata directory and an ns/ (namespace) directory.

Directory Structure

• .memkraft/:
  • agents/: JSON files for agent working memory.
  • channels/: JSON files for channel context.
  • tasks/: Task records and archives.
  • namespaces/: The core of v2.1, containing _registry.json (metadata and permissions), audit.jsonl (write audit logs), and locks/ (temporary lock files for concurrency control).
• ns/:
  • [namespace_name]/ (e.g., zeon/, sion/, shared/):
    • entities/: Markdown files for entities (e.g., simon.md).
    • facts/: Fact records.
    • daily/: Daily logs.
    • channels/: (In shared namespaces) for collaborative context.
• entities/, facts/, daily/: Legacy directories maintained for backward compatibility.

MKEP/0 is a runtime-neutral protocol for durable execution facts. It uses a specific request/response structure and a specialized JSON format called MKCJSON/1 to ensure deterministic digests.

Request Structure

Every request is a closed object containing:

• mkep: Protocol identifier
• kind: Type of request
• request_id: Unique identifier for the request
• op: The operation being performed
• target: The target of the operation
• args: Arguments for the operation
• precondition: (Optional) Required for apply requests
• now: (Optional) For clock-sensitive calls, callers must inject a timestamp in MKEP-TIME/1 format.

Response Structure

Responses are closed envelopes that indicate either success or error. They include a digest calculated over the fingerprint-normalized MKCJSON/1 representation of the object.

MKCJSON/1 Specification

To ensure deterministic hashing, MKCJSON/1 enforces the following:

• Keys: Must be ASCII and match the regex ^[a-z][a-z0-9_]{0,63}$. Keys are sorted.
• Types: Supports booleans, null, NFC strings, arrays, objects, and integers within the range $\pm(2^{53}-1)$.
• Prohibited: Floats and lone surrogates are rejected.
• Encoding: Compact separators, direct UTF-8 emission, and SHA-256 digests in lowercase hex over canonical logical objects (not the raw file bytes).