memkraft

v4.1.1 Current version: 4.1.1

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.

…

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:

…

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.

Hermes Agent

Hermes Agent includes a MemKraft memory-provider plugin. Install MemKraft in the same environment and configure the profile:

memory:
  provider: memkraft
plugins:
  memkraft:
    base_dir: $HERMES_HOME/memkraft-memory
    prefetch_top_k: 5

plugins.memkraft.source_path is only needed for an editable/source checkout. A normal wheel install imports memkraft from the active Python environment.

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

Method	Purpose
append_event(subject_id, key, value, source=...|provenance=...)	Append a sourced canonical event
compile_truth(dry_run=True)	Preview or build canonical compiled truth
current_truth(subject_id)	Read the applied truth view for one subject
sleep(strategy="default", dry_run=True)	Preview or apply a deterministic lifecycle transaction
forget(target, dry_run=True)	Preview or append a tombstone operation
compile_context(task, budget, ...)	Produce bounded, provenance-bearing context and a usage_id
report_outcome(usage_id, outcome, ...)	Append feedback for a recorded context usage

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

Entities, facts, and organization

Method	Purpose
init(path="")	Create the memory directory structure
track(name, entity_type="person", source="")	Start a tracked entity
update(name, info, source="manual")	Append sourced information to an entity
brief(name, save=False, file_back=False)	Compile an entity brief
list_entities()	List tracked entities
tier_set(name, tier) / promote(name, tier)	Set core, recall, or archival priority
fact_add(...)	Add a bitemporal fact
links(name)	Show backlinks for an entity
suggest_links()	Suggest missing wiki-links

Search and evidence

Method	Purpose
search(query, fuzzy=False, top_k=None, mode="legacy", ...)	Canonical search entry point
agentic_search(query, max_hops=2, context="", file_back=False)	Decompose, traverse links, and re-rank
lookup(query, brain_first=False, full=False)	Stop after sufficient high-relevance results unless full retrieval is requested
query(query="", level=1, ...)	Progressive disclosure: index, sections, or full text
compile_evidence_context(query, ...)	Build provenance-preserving evidence under a hard budget (preview)
aggregate_numeric_evidence(query, ...)	Compose explicit sum/count/duration evidence or fail closed (preview)

Audit, maintenance, and history

Method	Purpose
health_check()	Run memory assertions and return a score
dream(date=None, dry_run=False, resolve_conflicts=False)	Run legacy maintenance checks
decay(days=90, dry_run=False)	Flag stale facts with type-aware decay
dedup(dry_run=False)	Find and merge duplicate facts
resolve_conflicts(strategy="newest", dry_run=False)	Resolve detected contradictions
snapshot(label="", include_content=False)	Capture a point-in-time manifest
snapshot_diff(snapshot_a, snapshot_b="")	Compare snapshots or a snapshot with live state
time_travel(query, snapshot_id="", date="")	Search a captured past state
timeline(subject_id=None, ...)	Read the canonical event history
audit_log(action=None, subject=None, limit=None)	Read governance audit records
export_memory(include_tombstoned=False)	Export visible canonical memory

Agent continuity and scientific debugging

Method	Purpose
channel_save / channel_load	Persist per-channel context
task_start / task_update / task_list	Track task state and history
agent_save / agent_load / agent_inject	Persist and inject agent working context
start_debug(description)	Begin an OBSERVE → HYPOTHESIZE → EXPERIMENT → CONCLUDE session
`log