v4.4.0 Current version: 4.4.0

3.5.0 Verified Preview: The Python-only Adaptive ETA and Delay Ledger records private append-only run timing, deterministic estimates, anomalies, and inert retrospective evidence. Its contract and fail-closed replay behavior are covered by the 3.5.0 validation suite. It does not execute or schedule work.

3.6.0 Correction Learning: Corrections own append-only capture, revision, scope, scope-widening evaluation, and the exact complied / violated / not_applicable outcomes. The Improvement Ledger alone governs promotion, activation, and rollback. Injection uses a deterministic token estimate; the frozen benchmark verifies persisted outcome plumbing and marks two-host evidence not_ready, without claiming behavioral recurrence prevention.

MemKraft keeps its human-facing knowledge in files you can read, diff, edit, and version. Its core install uses the Python standard library, makes no model calls, and needs no API key. Your agent supplies the intelligence; MemKraft supplies persistent knowledge, provenance, lifecycle controls, and a feedback ledger.

Hermes Agent users can enable MemKraft as the active memory provider. The exact verified versions and profile-safe setup steps are in docs/HERMES_AGENT.md.

Why MemKraft

Most agent memory stops at store → search. MemKraft connects memory to what happened after recall:

• Own the source of truth. Entity pages, decisions, timelines, and notes are plain Markdown; local JSONL sidecars hold operational records such as canonical events and outcomes.
• Keep memory accountable. Canonical facts require a source or provenance, compiled truth is reconstructable, and retrieval preserves source links.
• Learn from use. compile_context() returns a stable usage_id; report_outcome() records success or failure and deterministically adjusts later context ordering.
• Govern explicitly. Forgetting, do-not-remember policies, tombstones, dry-run lifecycle operations, audit logs, and fail-closed reads are part of the system boundary.
• Stay model-agnostic. Use the CLI, Python API, MCP server, framework hints, or your own tool wrapper. MemKraft itself does not call an LLM.

Storage boundary: Markdown is the human-facing knowledge source of truth. MemKraft also maintains local .memkraft/ indexes, snapshots, canonical event logs, policies, and outcome records. Some governance operations hide or compact active local records; they do not promise deletion from Git history, backups, filesystem snapshots, or external copies.

Quickstart

Requires Python 3.9+. For an isolated CLI install:

pipx install memkraft
memkraft init
memkraft agents-hint claude-code >> AGENTS.md

Or install into the current Python environment:

pip install memkraft

memkraft init creates ./memory/ by default (or $MEMKRAFT_DIR). The generated resolver, templates, entity directories, and local state are ready for an agent to use.

memkraft track "Acme API" --type project --source "project docs"
memkraft update "Acme API" --info "Retries must use exponential backoff" --source "ADR-007"
memkraft search "retry policy"

Scaffold an integration-specific project instead:

memkraft init --template claude-code
memkraft init --template cursor
memkraft init --template mcp
memkraft init --template rag
memkraft init --template minimal
memkraft templates list

Templates are create-only and idempotent: re-running a template does not overwrite existing files.

The accountable memory loop

The host agent performs the action; MemKraft records what was recalled and what happened next.

from memkraft import MemKraft

mk = MemKraft("./memory")

# 1. Remember — canonical events require source or provenance.
mk.append_event(
    "deploy-agent",
    "rollback_rule",
    "Rollback when the 5xx rate stays above 2% for five minutes",
    source="runbook:production",
)
mk.compile_truth(dry_run=False)

# 2. Retrieve — fit provenance-bearing context into a hard token budget.
context = mk.compile_context(
    task="Deploy the API safely",
    budget=500,
    pinned_sources=["runbook:production"],
)
usage_id = context["usage_id"]

# 3. Act — your agent/model uses `context`; MemKraft does not dispatch it.
# result = agent.run(task="Deploy the API safely", context=context)

# 4. Report — append an outcome linked to the exact context usage.
mk.report_outcome(
    usage_id,
    outcome="success",
    reward=0.8,
    metadata={"idempotency_key": "deploy-2026-08-03"},
)

# 5. Improve — later compilation incorporates decayed outcome utility.
next_context = mk.compile_context(task="Deploy the API safely", budget=500)

The feedback update is bounded to ±20%, rewards are clamped to [-1, 1], and utility decays with a 30-day half-life. Reporting is append-only and can be made idempotent. Unknown usage IDs are rejected; pins, budgets, tombstones, provenance, and governance policies remain authoritative. See docs/V3_API.md for the exact contract.

A second, Markdown-native tuning loop tracks prompts and skills as first-class entities:

mk.prompt_register(
    "release-review",
    path="skills/release-review/SKILL.md",
    owner="platform",
    tags=["release", "quality"],
)

mk.prompt_eval(
    "release-review",
    iteration=1,
    scenarios=[{
        "name": "missing-migration",
        "description": "Release changes a storage contract",
        "requirements": [{"item": "flags migration risk", "critical": True}],
    }],
    results=[{
        "scenario": "missing-migration",
        "success": True,
        "accuracy": 100,
        "tool_uses": 3,
        "duration_ms": 1200,
        "unclear_points": [],
        "discretion": [],
    }],
)

past_evidence = mk.prompt_evidence("release-review", "migration risk")
verdict = mk.convergence_check("release-review", window=2)

Every iteration leaves inspectable decisions and links. MemKraft stores the report; your host agent runs the evaluation.

How it works

Knowledge and lifecycle

• Compiled truth + timeline: current state and the history that produced it.
• Bitemporal facts: record transaction time and fact-validity time.
• Tiers: core, recall, and archival control context priority.
• Links: [[wiki-links]] and backlinks connect entity pages.
• Reversible decay: stale memories can be deprioritized without immediate destruction.
• Snapshots and time travel: compare stored states and search a captured past view.
• Sleep: deterministic truth compilation; preview by default and apply explicitly.
• Candidates: session-scoped preview memory can be reviewed before durable promotion.

Retrieval

The canonical entry point is:

results = mk.search("retry policy", mode="smart", top_k=10)

Supported modes are legacy, v2, smart, and hybrid; the default remains legacy for backward compatibility. The older named methods search_v2(), search_smart(), and search_hybrid() remain compatibility aliases but emit DeprecationWarning; use search(..., mode=...) in new code.

Other retrieval tools include fuzzy search, brain-first lookup, multi-hop agentic search, progressive disclosure, goal/context-aware re-ranking, wiki-link traversal, optional local embeddings, query-focused evidence compilation, and fail-closed numeric aggregation.

hits = mk.agentic_search(
    "What failed during the last API rollout?",
    context="prepare today's deployment",
    file_back=True,
)

evidence = mk.compile_evidence_context(
    "What changed in the retry policy?",
    results=hits,
    top_k=10,
    budget=800,
)

compile_evidence_context() and aggregate_numeric_evidence() are preview APIs. Numeric aggregation only confirms explicit sum, count, or duration operations when units, provenance, and scope are unambiguous; otherwise it returns a non-success status rather than a partial answer.

Integrate an agent

Framework hints

agents-hint prints Markdown or JSON snippets for supported hosts:

memkraft agents-hint claude-code
memkraft agents-hint openclaw
memkraft agents-hint cursor
memkraft agents-hint openai
memkraft agents-hint mcp
memkraft agents-hint langchain

See examples/ for a minimal RAG flow, OpenAI function tools, and Claude Code guidance.

MCP

Install the optional dependency and run the stdio server:

pip install 'memkraft[mcp]'
python -m memkraft.mcp

Validate the local setup or run an isolated remember→search→recall smoke test:

memkraft mcp doctor
memkraft mcp test

Configuration examples for Claude Desktop and other MCP clients are in docs/mcp-setup.md.

OpenClaw

OpenClaw connects through the same MCP server. Use the absolute path of the Python that has memkraft[mcp] installed:

pip install 'memkraft[mcp]'
openclaw mcp set memkraft '{"command":"/ABSOLUTE/PATH/TO/python","args":["-m","memkraft.mcp"],"env":{"MEMKRAFT_DIR":"/ABSOLUTE/PATH/TO/memory"}}'
openclaw mcp show memkraft

memkraft agents-hint openclaw prints an AGENTS.md block that teaches the agent when to call MemKraft. With OpenClaw 2026.5.12, an isolated openclaw mcp set config plus a real MCP client round trip (remember → search → recall) was checked against the 4.2.2 wheel.

Hermes Agent

MemKraft registers itself as a Hermes memory provider through the hermes_agent.memory_providers entry point. Install it into the Python environment that runs Hermes, select it, and restart:

# use the same Python that runs Hermes (e.g. ~/.hermes/hermes-agent/.venv/bin/python)
python -m pip install --upgrade memkraft
hermes config set memory.provider memkraft
hermes gateway restart   # only when a gateway is running

Memory is stored in $HERMES_HOME/memkraft/ by default; set MEMKRAFT_DIR before starting Hermes to use another directory. No plugin directory copy is needed. A fresh Hermes 0.20.6 venv plus the 4.2.2 wheel was checked end to end: Hermes discovers and loads the provider, a completed turn is stored, and the next prefetch recalls it.

On Hermes versions that pass completed-turn messages to memory providers, MemKraft automatically compiles a failed development route followed by a final successful test/lint/build verification into sanitized ReasoningBank lessons. The next similar task receives bounded avoid/reuse guidance during prefetch. Raw tool arguments and outputs are not copied into these lessons, unverified failures are not promoted, and repeated sync of the same turn is idempotent. Set MEMKRAFT_HERMES_DEV_EXPERIENCE=off before starting Hermes to disable this behavior.

HERMES_HOME=/path/to/profile hermes memory status
HERMES_HOME=/path/to/profile hermes chat -Q --toolsets memory -q 'Call memkraft_status.'

Python API

The 3.x lifecycle contract is documented in docs/V3_API.md. The tables below keep the broader, long-lived API discoverable; preview surfaces are labeled separately.

Stable 3.x lifecycle core

track, update, search, why, and export_memory also remain public. Destructive lifecycle actions default to dry-run.

Entities, facts, and organization

Search and evidence

Audit, maintenance, and history

Agent continuity and scientific debugging

Preview and secondary APIs

The following are public but may gain additive fields or stricter validation in minor releases. Pin the MemKraft version if you persist their schemas as an external contract:

• Candidate/session memory: remember_candidate, list_candidates, session_overlay, forget_candidates
• Governance and compaction: do_not_remember, compact_memory, truth_status
• Claim pipeline: extract_claims, resolver_dry_run
• Interaction views: record_interaction, last_interaction
• Evidence helpers: compile_evidence_context, aggregate_numeric_evidence
• Local live sync: live_sync_apply, live_sync_events, live_sync_freshness, live_sync_repair
• Optional embedding maintenance: embedding_sync_path, embedding_index_state

See docs/V3_API.md for exact semantics and docs/MIGRATIONS.md for 2.13.x → 3.x migration and rollback guidance.

CLI reference

Run memkraft <command> --help for complete options.

Capture and retrieval

Lifecycle, maintenance, and audit

History, agents, and integrations

# Capture
memkraft extract "Acme API retries use exponential backoff." --source "ADR-007"
memkraft track "Acme API" --type project --source "project docs"

# Retrieve and feed the retrieval event back to the timeline
memkraft search "retry policy" --fuzzy --file-back
memkraft brief "Acme API"

# Inspect before changing lifecycle state
memkraft sleep
memkraft sleep --apply
memkraft doctor

# Preserve a checkpoint
memkraft snapshot --label before-release
memkraft stats --export json

Optional dependencies

The core package has no required third-party runtime dependencies. Install only the integrations you need:

pip install 'memkraft[mcp]'        # Model Context Protocol server
pip install 'memkraft[watch]'      # filesystem watcher
pip install 'memkraft[schedule]'   # scheduled lifecycle jobs
pip install 'memkraft[embedding]'  # local sentence-transformer retrieval
pip install 'memkraft[all]'        # all optional groups, including benchmark tooling

On-disk shape

A default workspace includes human-editable Markdown plus local operational state:

memory/
├── .memkraft/        # indexes, canonical events, policies, outcomes, snapshots
├── RESOLVER.md       # classification rules
├── TEMPLATES.md      # page templates
├── entities/         # people, organizations, projects, concepts
├── live-notes/       # actively tracked entities
├── decisions/        # decisions and rationale
├── originals/        # verbatim captures
├── inbox/            # unclassified input
├── meetings/         # briefs and notes
├── tasks/            # work-in-progress context
├── sessions/         # structured event logs
└── debug/            # hypothesis-driven debugging sessions

Derived indexes and compiled views are not authoritative. They can be rebuilt from source records; policy and tombstone checks remain part of reads.

Benchmarks and evidence

Memory Gym

The repository's deterministic, offline Memory Gym exercises lifecycle replay, provenance, governance, context budgets, outcome-linked ordering, and other release contracts. CI invokes each registered scenario with its advertised gate. See benchmarks/gym/ and the Gym workflow.

LongMemEval

The repository contains historical LongMemEval work, but it should be read with its limits intact. The durable evidence note records a 96.0% semantic self-judge result on a seeded 50-question oracle subset from a dirty 3.0.1 pre-final candidate. It was not a full-dataset run, not an independent-model judgment, and not final 3.1.0 validation. Automatic contains match on that run was 68.0%.

Read the complete setup, hashes, later experiments, and interpretation limits in docs/bench/longmemeval-3.0.1.md. MemKraft 3.1.0 makes no new external benchmark accuracy claim.

3.1.0 performance scope

Version 3.1.0 optimizes current_truth() by replacing repeated full-event scans with a per-call signature index, while retaining the legacy equality scan as a compatibility fallback. The release note reports local synthetic single-subject results and explicitly does not present them as universal latency claims. See docs/releases/3.1.0.md for methodology, measurements, validation, and limits.

3.2.0 local-first live sync

Version 3.2.0 replaces watcher's search-ping side effect with explicit path invalidation, records compact provenance-linked change envelopes, reports canonical-to-derived freshness, repairs disposable indexes from Markdown, and updates an existing optional embedding index one document at a time. Markdown remains canonical, BM25 remains the default retriever, and no dependency was added to the core. See docs/LIVE_SYNC.md and the release notes.

4.2.1 large-store recall

Version 4.2.1 computes the corpus fingerprint straight from os.scandir stat data and builds per-file Path objects only when the index must be rebuilt. The read cache keeps one entry per path, so cache misses and invalidation no longer scan every resident entry. Hermes prefetch now widens its candidate window (12 → 80 → 240) until real documents surface past chat-derived template entity pages.

On a copy of one real 30,082-file Hermes store (single macOS machine), uncached search(top_k=20) medians fell from 333/245/298 ms to 160/132/158 ms across three queries, and a deploy/install prefetch went from 5 of 5 template pages to 0 of 5. These are local measurements on one store, not universal latency claims. See docs/releases/4.2.1.md.

4.2.2 cold-start recall

A restarted process no longer re-reads and re-tokenizes the whole store before its first search. Per-document token maps and derived postings are cached in .memkraft/index/ and keyed by each file's (mtime_ns, size), so only changed files are re-read. The cache is disposable: corruption or a tokenizer change falls back to a normal rebuild. On the same 30,082-file store copy, the first Hermes prefetch after a restart dropped from 2.0-3.9 s to about 0.55 s, and new-question prefetch medians dropped from 123-434 ms to 12-140 ms. These are local single-store measurements.

4.3.0 curated work lessons

Auto-captured ReasoningBank lessons describe tool errors ("avoid read_file; tool-error"). Workflow mistakes, such as retrying the same failing upload many times or not reporting progress, were never captured. memkraft lesson add <id> --rule "..." --triggers "word,word" --example "real request" stores such a rule. It is recalled whenever a new request shares a trigger word, ranks above auto-captured detours, and memkraft lesson check fails if a stored example would no longer recall its rule. Recall also drops host-quoted reply context and matches Korean stems ("크기를" → "크기"). On a copy of one real Korean-chat store, the right rule ranked first for 6 of 6 real requests (2 of 6 before). See docs/releases/4.3.0.md.

Safety and operational notes

• sleep and forget are dry-run by default; use explicit apply calls for writes.
• cognify recommends destinations unless --apply is supplied.
• Canonical events require non-empty source or provenance.
• Corrupt canonical event, policy, or compiled snapshots fail closed rather than reviving hidden data.
• do_not_remember and tombstones govern visibility; they are not guarantees of physical erasure from external copies.
• selfupdate changes the installed package. In agent automation, ask for human approval before upgrading.
• Local Markdown can contain sensitive information. Apply normal filesystem permissions, backup, and repository-access controls.

The full threat model is in docs/THREAT_MODEL.md.

Versioning and upgrades

Current version: 4.4.0.

pipx upgrade memkraft
# or
pip install --upgrade memkraft

memkraft --version

Upgrading from 4.3.1 to 4.4.0 requires no migration; chat-sourced auto extraction is gated by default (MEMKRAFT_WRITE_GATE=preview|off restores the old writes) and memkraft gate-archive is opt-in. Upgrading from 4.3.0 to 4.3.1 requires no migration; MEMKRAFT_OWNER_DIR now also applies to plain MemKraft(base_dir=...) stores. Upgrading from 4.2.x to 4.3.0 requires no migration command or Markdown rewrite. Curated lessons are ordinary ReasoningBank trajectories tagged curated-lesson; older versions read them as plain failure lessons.

Upgrading from 4.2.x to 4.2.2 requires no migration command or Markdown rewrite. The first search writes a disposable token cache to .memkraft/index/; deleting it is always safe, and MEMKRAFT_INDEX_CACHE=off disables it.

Upgrading from 3.4.1 to 3.5.0 requires no migration command or Markdown rewrite. Adaptive ETA reads do not create state; the first delay-ledger write lazily creates the additive .memkraft/delay/events.jsonl store. To roll back, stop 3.5.0 writers and reinstall 3.4.1. It ignores .memkraft/delay/, so preserve that directory for audit and for a later re-upgrade; deleting it is explicit loss of delay evidence. Do not let 3.5.0 and 3.4.1 processes write the same base directory concurrently. For API compatibility boundaries, read docs/V3_API.md; for older migrations and rollback, read docs/MIGRATIONS.md.

📝 Changelog

v4.4.0 (current)

Rule-based write gate for chat-sourced auto extraction and a reversible memkraft gate-archive. See release notes.

v4.3.1

Scripts and cron jobs share the owner ledger through MEMKRAFT_OWNER_DIR; new memkraft owner CLI. See release notes.

v4.3.0

Curated work lessons (memkraft lesson add|list|check) recalled before similar tasks; ReasoningBank recall ignores quoted reply context and matches Korean stems. See release notes.

v4.2.2

Cold first search on large stores is 4-7x faster through a persistent token cache; Hermes recall skips redundant stat scans. See release notes.

v4.2.1

Faster recall on large stores and template-safe Hermes prefetch. See release notes.

v4.2.0

Adds a verbatim owner-sayings ledger and an irreversible-only decision queue, exposed to Hermes as owner_* tools. See release notes.

v4.1.2

Makes Delay Ledger writes linear in ledger size, removing a per-tool-step stall on long-running Hermes installs. See release notes.

v4.1.1

Adds deterministic WikiSkill records; automatic host injection is not included. See release notes.

v4.1.0

MemKraft 4.1.0 adds a default-on Hermes capability bundle for adaptive ETA, remaining-time and phase learning, plus conservative development-detour learning. Read the release notes.

v4.0.2

MemKraft 4.0.2 adds a host-neutral JSON-stdio agent bridge, idempotent setup metadata, and integration diagnostics. Read the release notes.

v3.7.0

MemKraft 3.7.0 adds an additive typed Memory Graph for accountable claims, artifacts, relations, lifecycles, provenance paths, guarded atomic mutation, exact-first retrieval, strict replay, and CLI inspection. Existing APIs and legacy stores remain compatible. Read the release notes.

v3.6.2

MemKraft 3.6.2 adds structured completed-content artifacts with exact phrase and provenance-scoped retrieval. It preserves direct source turns over summaries, does not invent missing runtime metadata, and publishes artifact metadata atomically. Read the release notes.

v3.6.1

MemKraft 3.6.1 is the publishable integrity patch for the 3.6 Correction Learning line. It binds promoted ledger evidence to the exact injected correction payload, verifies visible persisted correction metadata on replay, and preserves legacy Hermes extraction for callers that do not provide role messages. Read the release notes.

v3.6.0

MemKraft 3.6.0 adds opt-in Correction Learning with governed scoped policies, bounded deterministic injection, outcome tracking, and a frozen accuracy and latency gate. Read the release notes.

v3.5.2

MemKraft 3.5.2 makes selfupdate --converge select the highest published stable release and preserves the official wheel filename required by pip. Read the release notes.

v3.5.1

MemKraft 3.5.1 adds fail-closed installation integrity diagnostics and explicit convergence to a hash-verified official PyPI wheel. Read the release notes.

v3.5.0

MemKraft 3.5.0 is the active development release line after the immutable v3.4.1 baseline. Its verified Adaptive ETA and Delay Ledger Preview is Python-only and additive. Read the release notes.

v3.4.1

MemKraft 3.4.1 consolidates the runtime-neutral MKEP/0 execution Preview, Evaluation Corpus, Continual Improvement Ledger Preview, Project State Contract, and a fail-closed single-release-lineage gate. It also fixes the release verifier source-path boundary found by the failed, unpublished v3.4.0 workflow. Read the release notes.

v3.2.0

MemKraft 3.2.0 adds local-first live sync, freshness diagnostics and repair, provenance-linked file change events, and optional single-path embedding updates without changing canonical storage or default retrieval. Read the release notes.

v3.1.0

The 3.1.0 release strengthens accountable retrieval, lifecycle controls, and performance while preserving the local-first Markdown storage model. Read the release notes or browse the complete CHANGELOG.md.

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md for the development workflow.

Inspirations and credits

MemKraft draws on ideas from tiered agent memory, temporal knowledge, scientific debugging, structured wikis, and evidence-driven iteration. Project-specific acknowledgements and links are preserved below.

License

MIT