Metadata-Version: 2.4
Name: memkraft
Version: 4.4.0
Summary: The compound knowledge system for AI agents
Author-email: Seojun Kim <simonkim.nft@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/seojoonkim/memkraft
Project-URL: Repository, https://github.com/seojoonkim/memkraft
Project-URL: Documentation, https://github.com/seojoonkim/memkraft/tree/main/docs
Project-URL: Bug Tracker, https://github.com/seojoonkim/memkraft/issues
Project-URL: Changelog, https://github.com/seojoonkim/memkraft/blob/main/CHANGELOG.md
Keywords: ai,agents,memory,knowledge-graph,compound,cli,pipx,mcp
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Environment :: Console
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: version-drift
Requires-Dist: version-drift<0.2.0,>=0.1.0; extra == "version-drift"
Provides-Extra: mcp
Requires-Dist: mcp<2.0,>=1.0; extra == "mcp"
Provides-Extra: watch
Requires-Dist: watchdog>=3.0; extra == "watch"
Provides-Extra: bench
Requires-Dist: anthropic>=0.18.0; extra == "bench"
Provides-Extra: schedule
Requires-Dist: apscheduler>=3.10; extra == "schedule"
Provides-Extra: embedding
Requires-Dist: sentence-transformers<6,>=2.2; extra == "embedding"
Requires-Dist: numpy>=1.21; extra == "embedding"
Provides-Extra: all
Requires-Dist: mcp<2.0,>=1.0; extra == "all"
Requires-Dist: watchdog>=3.0; extra == "all"
Requires-Dist: anthropic>=0.18.0; extra == "all"
Requires-Dist: apscheduler>=3.10; extra == "all"
Requires-Dist: sentence-transformers<6,>=2.2; extra == "all"
Requires-Dist: numpy>=1.21; extra == "all"
Dynamic: license-file

**v4.4.0**
Current version: **4.4.0**

<div align="center">

# MemKraft

**Local-first, plain-Markdown compound knowledge and accountable self-improvement for AI agents.**

Remember sourced facts. Retrieve bounded context. Act with any model or agent. Report the result. Let evidence improve the next retrieval.

[![PyPI](https://img.shields.io/pypi/v/memkraft.svg)](https://pypi.org/project/memkraft/)
[![Python](https://img.shields.io/pypi/pyversions/memkraft.svg)](https://pypi.org/project/memkraft/)
[![Tests](https://img.shields.io/github/actions/workflow/status/seojoonkim/memkraft/gym-gate.yml?label=tests)](https://github.com/seojoonkim/memkraft/actions/workflows/gym-gate.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

[Quickstart](#quickstart) · [The loop](#the-accountable-memory-loop) · [Python API](#python-api) · [CLI](#cli-reference) · [Hermes Agent](docs/HERMES_AGENT.md) · [MCP](docs/mcp-setup.md)

</div>

> **3.5.0 Verified Preview:** The Python-only [Adaptive ETA and Delay Ledger](docs/ADAPTIVE_ETA_DELAY_LEDGER.md) 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`](docs/HERMES_AGENT.md).

<p align="center">
  <img src="assets/readme/agent-loop.svg" width="100%" alt="MemKraft loop: remember sourced facts, retrieve budgeted context, act, report an outcome, and improve the next retrieval">
</p>

## 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:

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

Or install into the current Python environment:

```bash
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.

```bash
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:

```bash
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.

```python
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`](docs/V3_API.md) for the exact contract.

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

```python
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:

```python
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.

```python
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:

```bash
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/`](examples/) for a minimal RAG flow, OpenAI function tools, and Claude Code guidance.

### MCP

Install the optional dependency and run the stdio server:

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

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

```bash
memkraft mcp doctor
memkraft mcp test
```

Configuration examples for Claude Desktop and other MCP clients are in [`docs/mcp-setup.md`](docs/mcp-setup.md).

### OpenClaw

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

```bash
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:

```bash
# 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.

```bash
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`](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_hypothesis` / `log_evidence` | Record theories and test results |
| `reject_hypothesis` / `confirm_hypothesis` | Preserve failed and confirmed approaches |
| `search_debug_sessions` / `search_rejected_hypotheses` | Reuse past debugging evidence |
| `development_capture_turn(task, messages, session_id=...)` | Compile verified, sanitized development detours into ReasoningBank |
| `development_inject_for_task(task_query, ...)` | Retrieve bounded avoid/reuse guidance for a similar task |

### 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`](docs/V3_API.md) for exact semantics and [`docs/MIGRATIONS.md`](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

| Command | Purpose |
| --- | --- |
| `init [--path DIR] [--template NAME]` | Initialize memory or apply a scaffold |
| `templates list` | List built-in scaffolds |
| `track NAME [--type T] [--source S]` | Track an entity |
| `update NAME --info INFO [--source S]` | Append entity information |
| `extract TEXT [--source S] [--dry-run] [--confidence C]` | Extract entities and facts |
| `detect TEXT [--source S] [--dry-run]` | Detect EN/KR/CN/JP entities |
| `search QUERY [--fuzzy] [--file-back]` | Search memory files |
| `agentic-search QUERY [--max-hops N] [--context C] [--file-back]` | Multi-step retrieval |
| `lookup QUERY [--brain-first] [--full]` | Brain-first lookup |
| `query [QUERY] [--level 1\|2\|3]` | Progressive disclosure query |
| `brief NAME [--save] [--file-back]` | Generate an entity brief |
| `links NAME` | Show backlinks |

### Lifecycle, maintenance, and audit

| Command | Purpose |
| --- | --- |
| `sleep [--dry-run\|--apply]` | Preview or apply canonical truth compilation |
| `cognify [--dry-run] [--apply]` | Route inbox content into structured pages |
| `health-check` | Run memory assertions |
| `dream [--dry-run] [--resolve-conflicts]` | Run legacy maintenance |
| `resolve-conflicts [--strategy S] [--dry-run]` | Resolve contradictions |
| `decay [--days N] [--dry-run]` | Flag stale facts |
| `dedup [--dry-run]` | Merge duplicates |
| `summarize [NAME] [--max-length N]` | Condense entity pages |
| `diff` | Show changes since maintenance |
| `open-loops [--dry-run]` | Find TODO, FIXME, and pending items |
| `doctor [--check-updates] [--fix] [--dry-run]` | Check installation and memory structure |
| `stats [--export json\|csv\|human]` | Report workspace statistics |

### History, agents, and integrations

| Command | Purpose |
| --- | --- |
| `snapshot [--label L] [--include-content]` | Capture a snapshot |
| `snapshot-list` / `snapshot-diff` | List or compare snapshots |
| `time-travel QUERY [--snapshot ID] [--date YYYY-MM-DD]` | Search a past snapshot |
| `snapshot-entity NAME` | Show entity evolution across snapshots |
| `debug ...` | Run the hypothesis-tracking workflow |
| `channel-save`, `channel-load`, `channel-update` | Manage channel context |
| `task-start`, `task-update`, `task-list`, `task-delegate` | Manage task continuity |
| `agent-save`, `agent-load`, `agent-inject`, `agent-handoff` | Manage agent working memory |
| `agents-hint TARGET [--format markdown\|json]` | Generate integration instructions |
| `mcp doctor` / `mcp test` | Validate MCP readiness or run a local round trip |
| `watch [--path PATH] [--once]` | Watch and re-index; requires `memkraft[watch]` |
| `freshness [--path DIR] [--repair] [--json]` | Diagnose or rebuild derived indexes from canonical Markdown |
| `selfupdate [--dry-run]` | Upgrade via pip when a newer PyPI version exists |

<details>
<summary><strong>Daily CLI recipe</strong></summary>

```bash
# 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
```

</details>

## Optional dependencies

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

```bash
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:

```text
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/`](benchmarks/gym/) and the [Gym workflow](.github/workflows/gym-gate.yml).

### 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`](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`](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`](docs/LIVE_SYNC.md) and the [release notes](docs/releases/3.2.0.md).

### 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`](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`](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`](docs/THREAT_MODEL.md).

## Versioning and upgrades

Current version: **4.4.0**.

```bash
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`](docs/V3_API.md); for older migrations and rollback, read [`docs/MIGRATIONS.md`](docs/MIGRATIONS.md).

## 📝 Changelog

### [v4.4.0](https://github.com/seojoonkim/memkraft/releases/tag/v4.4.0) (current)

Rule-based write gate for chat-sourced auto extraction and a reversible `memkraft gate-archive`. See [release notes](docs/releases/4.4.0.md).

### [v4.3.1](https://github.com/seojoonkim/memkraft/releases/tag/v4.3.1)

Scripts and cron jobs share the owner ledger through `MEMKRAFT_OWNER_DIR`; new `memkraft owner` CLI. See [release notes](docs/releases/4.3.1.md).

### [v4.3.0](https://github.com/seojoonkim/memkraft/releases/tag/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](docs/releases/4.3.0.md).

### [v4.2.2](https://github.com/seojoonkim/memkraft/releases/tag/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](docs/releases/4.2.2.md).

### [v4.2.1](https://github.com/seojoonkim/memkraft/releases/tag/v4.2.1)

Faster recall on large stores and template-safe Hermes prefetch. See [release notes](docs/releases/4.2.1.md).

### [v4.2.0](https://github.com/seojoonkim/memkraft/releases/tag/v4.2.0)

Adds a verbatim owner-sayings ledger and an irreversible-only decision queue, exposed to Hermes as `owner_*` tools. See [release notes](docs/releases/4.2.0.md).

### [v4.1.2](https://github.com/seojoonkim/memkraft/releases/tag/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](docs/releases/4.1.2.md).

### [v4.1.1](https://github.com/seojoonkim/memkraft/releases/tag/v4.1.1)

Adds deterministic WikiSkill records; automatic host injection is not included. See [release notes](docs/releases/4.1.1.md).

### [v4.1.0](https://github.com/seojoonkim/memkraft/releases/tag/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](docs/releases/4.1.0.md).

### [v4.0.2](https://github.com/seojoonkim/memkraft/releases/tag/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](docs/releases/4.0.2.md).

### [v3.7.0](https://github.com/seojoonkim/memkraft/releases/tag/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](docs/releases/3.7.0.md).

### [v3.6.2](https://github.com/seojoonkim/memkraft/releases/tag/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](docs/releases/3.6.2.md).

### [v3.6.1](https://github.com/seojoonkim/memkraft/releases/tag/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](docs/releases/3.6.1.md).

### [v3.6.0](https://github.com/seojoonkim/memkraft/releases/tag/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](docs/releases/3.6.0.md).

### [v3.5.2](https://github.com/seojoonkim/memkraft/releases/tag/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](docs/releases/3.5.2.md).

### [v3.5.1](https://github.com/seojoonkim/memkraft/releases/tag/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](docs/releases/3.5.1.md).

### [v3.5.0](https://github.com/seojoonkim/memkraft/releases/tag/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](docs/releases/3.5.0.md).

### [v3.4.1](https://github.com/seojoonkim/memkraft/releases/tag/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](docs/releases/3.4.1.md).

### [v3.2.0](https://github.com/seojoonkim/memkraft/releases/tag/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](docs/releases/3.2.0.md).

### [v3.1.0](https://github.com/seojoonkim/memkraft/releases/tag/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](docs/releases/3.1.0.md) or browse the complete [`CHANGELOG.md`](CHANGELOG.md).

## Contributing

Issues and pull requests are welcome. See [`CONTRIBUTING.md`](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.

<details>
<summary><strong>View inspirations</strong></summary>

- [Karpathy auto-research](https://x.com/karpathy/status/1906697764923920553) — evidence-based autonomous research
- [Shen Huang's debug-hypothesis skill](https://github.com/LichAmnesia/lich-skills/tree/main/skills/debug-hypothesis) — scientific debugging
- [Letta / MemGPT](https://github.com/letta-ai/letta) — tiered memory architecture
- [mem0](https://github.com/mem0ai/mem0) — agent memory extraction and retrieval patterns
- [Zep](https://github.com/getzep/zep) — temporal memory and entity extraction
- [MemoryWeaver](https://github.com/pchaganti/gx-memory-weaver) — dialectic synthesis and reconstruction
- [Karpathy llm-wiki](https://x.com/karpathy/status/2042079355925164424) — wiki-style structured knowledge for LLMs

</details>

## License

[MIT](LICENSE)

<div align="center">

[GitHub](https://github.com/seojoonkim/memkraft) · [PyPI](https://pypi.org/project/memkraft/) · [Issues](https://github.com/seojoonkim/memkraft/issues)

</div>
