MemKraft 🧠

Bitemporal memory × empirical tuning: the first self-improvement ledger for AI agents. Your agent's accountable past, in plain Markdown.

🏆 LongMemEval 98.0% — #1 on open-source agent long-term memory benchmarks (Surpasses MemPalace 96.6%, MEMENTO by Microsoft 90.8% · LLM-as-judge · oracle 50 · 3-run semantic majority)

v2.7.0 · Zero-dependency compound knowledge system for AI agents. Auto-extract, classify, search, tune, and time-travel — all in plain Markdown. Debugging is memory. Time travel is memory. Multi-agent handoffs are memory. Facts have bitemporal validity. Memories decay reversibly. Wiki links build graphs. Tuning iterations leave an audit trail.

Plain Markdown source-of-truth · zero deps · zero keys · zero LLM calls inside MemKraft. In 30 seconds: pipx install memkraft && memkraft init && memkraft agents-hint claude-code

📖 Table of Contents

• ⚡ Quickstart (30s)
• 🎯 Why MemKraft?
• 🧩 Features
• 🍳 Real-world Recipes
• 🔬 Specialized Features
• 📚 API Reference
• ⌨️ CLI Reference
• 🏗️ Architecture
• ⚖️ Comparison
• 🏆 Reproducing LongMemEval
• 🆙 Staying Up To Date
• 📝 Changelog
• 🤝 Contributing
• 📄 License
• 🙏 Appendix: Inspirations & Credits

⚡ Quickstart (30s)

pip install memkraft
memkraft init                   # → creates ./memory/ with RESOLVER, TEMPLATES, entities/, ...
memkraft agents-hint claude-code >> AGENTS.md   # your agent is now memory-aware

Or scaffold a full project

memkraft init --template claude-code   # CLAUDE.md + memory/ + examples
memkraft init --template cursor        # .cursorrules + memory/
memkraft init --template mcp           # claude_desktop_config snippet + memory/
memkraft init --template rag           # retrieval-focused structure
memkraft init --template minimal       # just memory/entities/
memkraft templates list                # see all presets

Templates are idempotent — re-running init --template X never overwrites your edits.

Or in Python:

from memkraft import MemKraft
mk = MemKraft("./memory"); mk.init()
mk.track("Simon Kim", entity_type="person", source="news")
mk.update("Simon Kim", info="Launched MemKraft 0.8.1", source="PyPI")
mk.search("MemKraft")

That's it. Your agent now has persistent memory as plain markdown files. No API keys. No database. No config. Just .md files you own.

Optional extras

pip install 'memkraft[mcp]'      # + MCP server  (`python -m memkraft.mcp`)
pip install 'memkraft[watch]'    # + auto-reindex on save (`memkraft watch`)
pip install 'memkraft[all]'      # everything

Connect Any Agent in 30 Seconds

memkraft agents-hint <target> prints copy-paste-ready integration snippets:

memkraft agents-hint claude-code   # → CLAUDE.md / AGENTS.md block
memkraft agents-hint openclaw      # → AGENTS.md block for ОpenClaw
memkraft agents-hint cursor        # → .cursorrules block
memkraft agents-hint openai        # → Custom GPT / function-calling schema
memkraft agents-hint mcp           # → claude_desktop_config.json snippet
memkraft agents-hint langchain     # → LangChain StructuredTool wrappers

Paste the output. Done. Or pipe it straight into your config:

memkraft agents-hint claude-code >> AGENTS.md

See examples/ for runnable variants.

🎯 Why MemKraft?

What Makes MemKraft Different

API overview (14 public methods)

Also new in 2.6: silent contradiction detection on fact_add, plus 1-hop graph neighbor expansion for counting-style queries (how many, list all).

New in 2.7: in-process search result caching for search_v2() and search_smart() — thread-safe LRU + TTL (default capacity 256, TTL 300s). Mutations (update, track, fact_add, log_event, consolidate, decision_record, dream_cycle) auto-invalidate via a generation counter, so callers never need to think about cache coherence. Opt-out per call with cache=False. Measured 6.14x speedup on a hot-path workload (152 → 931 qps) and 1.65x on a 50/50 mixed workload — raw numbers in benchmarks/v2.7.0-bench-result.json. Zero breaking changes.

Self-improvement loop: register → tune → recall → decide, every step auditable and time-travelable. See MIGRATION.md for upgrading from 0.9.x (zero breaking changes).

The 1.0 Self-Improvement Loop

Register a prompt/skill, record iterations, cite past evidence, and let MemKraft auto-judge when to stop tuning — all in plain Markdown, no LLM calls inside MemKraft:

from memkraft import MemKraft
mk = MemKraft("./memory")

# 1. register a prompt/skill as a first-class entity
mk.prompt_register(
    "my-skill",
    path="skills/my-skill/SKILL.md",
    owner="zeon",
    tags=["tuning"],
)

# 2. record each empirical iteration (host agent dispatches the run
#    — MemKraft only persists the report)
mk.prompt_eval(
    "my-skill",
    iteration=1,
    scenarios=[{
        "name": "parallel-dispatch",
        "description": "3 subagents at once",
        "requirements": [{"item": "all return", "critical": True}],
    }],
    results=[{
        "scenario": "parallel-dispatch",
        "success": True, "accuracy": 85,
        "tool_uses": 5, "duration_ms": 2000,
        "unclear_points": ["schema missing"],
        "discretion": [],
    }],
)

# 3. cite past iterations before the next run
mk.prompt_evidence("my-skill", "accuracy regression")

# 4. stop when the last N iterations stabilise
verdict = mk.convergence_check("my-skill", window=2)
# -> {"converged": False, "reason": "insufficient-iters",
#     "iterations_checked": [1],
#     "suggested_next": "patch-and-iterate", ...}

Each call leaves an auditable trail on disk: a decision record per iteration, an incident when unclear points pile up, and wiki-links between iterations. Upgrade is zero-breaking from 0.9.x — see MIGRATION.md.

Ingestion & Extraction

Search & Retrieval

Structure & Organization

Maintenance & Audit

Logging & Reflection

Debugging

🍳 Real-world Recipes

memkraft init
memkraft extract "Simon Kim is the CEO of Hashed in Seoul." --source "news"
memkraft brief "Simon Kim"
memkraft doctor                          # 🟢/🟡/🔴 health check with fix hints
memkraft doctor --fix --yes              # auto-repair missing structure (create-only, never deletes)
memkraft stats --export json             # workspace stats for CI dashboards
memkraft mcp doctor                      # validate MCP server readiness
memkraft mcp test                        # remember→search→recall smoke test

MCP (Claude Desktop / Cursor) setup: see docs/mcp-setup.md.

Python Usage

from memkraft import MemKraft

mk = MemKraft("/path/to/memory")
mk.init()  # returns {"created": [...], "exists": [...], "base_dir": "..."}

# Extract entities & facts from text
mk.extract_conversations("Simon Kim is the CEO of Hashed.", source="news")

# Track an entity
mk.track("Simon Kim", entity_type="person", source="news")
mk.update("Simon Kim", info="Launched MemKraft", source="X/@simonkim_nft")

# Search with fuzzy matching
results = mk.search("venture capital", fuzzy=True)

# Agentic multi-hop search with context-aware re-ranking
results = mk.agentic_search(
    "who is the CEO of Hashed",
    context="crypto investment research",  # Conway SMS: same query, different context → different ranking
    file_back=True,  # feedback loop: results auto-filed back to entity timelines
)

# Run health check (5 self-diagnostic assertions)
report = mk.health_check()
# → {"pass_rate": 80.0, "health_score": "A", ...}

# Dream Cycle - nightly maintenance
mk.dream(dry_run=True)

# 1. Extract & Track - auto-detect entities from any text
memkraft extract "Simon Kim is the CEO of Hashed in Seoul." --source "news"
memkraft extract "Revenue grew 85% YoY" --confidence verified --when "bull market"
memkraft track "Simon Kim" --type person --source "X/@simonkim_nft"
memkraft update "Simon Kim" --info "Launched MemKraft" --source "X/@simonkim_nft"

# 2. Search & Recall - find anything in your memory
memkraft search "venture capital" --fuzzy
memkraft search "Seoul VC" --file-back           # feedback loop: auto-file to timelines
memkraft lookup "Simon" --brain-first
memkraft agentic-search "who is the CEO of Hashed" --context "meeting prep"

# 3. Meeting Prep - compile all context before a meeting
memkraft brief "Simon Kim"
memkraft brief "Simon Kim" --file-back            # record brief generation in timeline
memkraft links "Simon Kim"

# 4. Ingest & Classify - inbox → structured pages (safe by default)
memkraft cognify            # recommend-only; add --apply to move files
memkraft detect "Jack Ma and 马化腾 discussed AI" --dry-run

# 5. Log & Reflect - structured audit trail
memkraft log --event "Deployed v0.3" --tags deploy --importance high
memkraft retro              # daily Well / Bad / Next retrospective

# 6. Maintain & Heal - Dream Cycle keeps memory healthy
memkraft health-check       # 5 assertions → pass rate + health score (A/B/C/D)
memkraft dream --dry-run    # nightly: sources, duplicates, bloated pages
memkraft resolve-conflicts --strategy confidence  # resolve contradictory facts
memkraft diff               # what changed since last maintenance?
memkraft open-loops         # find all unresolved items

# 7. Debug Hypothesis Tracking - "Debugging is Memory"
memkraft debug start "API returns 500 on POST /users"
memkraft debug hypothesis "Database connection timeout"
memkraft debug evidence "DB pool healthy" --result contradicts
memkraft debug reject --reason "DB is fine"
memkraft debug hypothesis "Request validation missing"
memkraft debug evidence "Empty POST triggers 500" --result supports
memkraft debug confirm
memkraft debug end "Added request body validation"
memkraft debug search-rejected "timeout"  # avoid past mistakes

This section gathers features that deserve a closer look: time-travel snapshots, multi-agent context plumbing, autonomous memory lifecycle, and scientific debugging.

📸 Memory Snapshots & Time Travel (v0.5.1)

from memkraft import MemKraft

mk = MemKraft("/path/to/memory")

# Take a snapshot before a big operation
snap = mk.snapshot(label="before-migration", include_content=True)

# ... time passes, memory changes ...

# What changed?
diff = mk.snapshot_diff(snap["snapshot_id"])  # vs live state
# → {added: [...], removed: [...], modified: [...], unchanged_count: 42}

# Search memory as it was at that snapshot
results = mk.time_travel("venture capital", snapshot_id=snap["snapshot_id"])

# How did an entity evolve over time?
timeline = mk.snapshot_entity("Simon Kim")
# → [{snapshot_id, timestamp, fact_count, size, change_type: "new"}, ...]

🧠 Channel Context Memory + Task Continuity + Agent Working Memory (v0.5.4)

from memkraft import MemKraft

mk = MemKraft("/path/to/memory")

# Save channel context
mk.channel_save("telegram-46291309", {
    "summary": "DM with Simon",
    "recent_tasks": ["vibekai deploy", "memkraft v0.5.4"],
    "preferences": {"language": "ko"},
})

# Register a task
mk.task_start("deploy-001", "Deploy vibekai to production",
              channel_id="telegram-46291309", agent="zeon")
mk.task_update("deploy-001", "active", "vercel build passed")

# Save agent working memory
mk.agent_save("zeon", {
    "key_context": "Simon's AI assistant",
    "active_tasks": ["deploy-001"],
    "learned": ["always report completion", "no silence"],
})

# Inject merged context block into a sub-agent instruction
block = mk.agent_inject("zeon",
                        channel_id="telegram-46291309",
                        task_id="deploy-001")
print(block)
# ## Agent Working Memory
# - **key_context:** Simon's AI assistant
# - **active_tasks:** deploy-001
# ...
# ## Channel Context
# - **summary:** DM with Simon
# ...
# ## Task Context
# - **Task:** Deploy vibekai to production
# - **Status:** active
# - **History:**
#   - [2026-04-15T...] active: vercel build passed

🤖 Autonomous Memory Management (v1.1.0)

"Memory should manage itself."

Memory tends to grow without limit — agents add entries but rarely clean up. MemKraft 1.1.0 solves this with a self-managing lifecycle.

The Problem

• Add-only pattern: agents append to MEMORY.md every session, never prune
• Silent maintenance failures: nightly cleanup crons fail without notice
• No lifecycle: every memory entry treated equally, forever

The Solution: flush → compact → digest

from memkraft import MemKraft
mk = MemKraft(base_dir="memory/")

# 1. Import existing MEMORY.md → structured MemKraft data
mk.flush("MEMORY.md")

# 2. Auto-archive old/low-priority items
result = mk.compact(max_chars=15000)
# → {"moved": 47, "freed_chars": 89400, ...}

# 3. Re-render MEMORY.md — always ≤ 15KB
mk.digest("MEMORY.md")
# → {"chars": 11700, "truncated": False}

# 4. Check memory health
health = mk.health()
# → {"status": "healthy", "total_chars": 11700, "recommendations": [...]}

Real-world result

Our MEMORY.md grew to 153KB (1,862 lines) over weeks of agent sessions. After flush → compact → digest: 11.7KB (170 lines). 92% reduction.

Nightly self-cleanup recipe

# Watch for real-time sync
mk.watch("memory/", on_change="flush", interval=300)

# Or set a nightly schedule (requires: pip install memkraft[schedule])
mk.schedule([
    lambda: mk.compact(max_chars=15000),
    lambda: mk.digest("MEMORY.md"),
], cron_expr="0 23 * * *")

🐛 Debugging is Memory

Debugging insights are too valuable to lose in scrollback. MemKraft treats the entire debug process as first-class memory.

The debug-hypothesis loop - inspired by Shen Huang's scientific debugging method:

OBSERVE → HYPOTHESIZE → EXPERIMENT → CONCLUDE
    ↑                        |
    |    rejected?           |
    +←── next hypothesis ←───+
    |
    all rejected? → back to OBSERVE

• mk.start_debug("bug description") - begin a tracked session
• mk.log_hypothesis(bug_id, "theory", "evidence") - record each theory
• mk.log_evidence(bug_id, hyp_id, "test result", "supports|contradicts") - track proof
• mk.reject_hypothesis(bug_id, hyp_id, "reason") - mark failed approaches
• mk.confirm_hypothesis(bug_id, hyp_id) - lock in the root cause
• mk.end_debug(bug_id, "resolution") - close session, feed back to memory

Why it matters: rejected hypotheses are permanent memory. Next time you hit a similar bug, MemKraft surfaces what you already tried - no more repeating the same failed approaches.

MemKraft(base_dir=None)

Initialize the memory system. If base_dir is not provided, uses $MEMKRAFT_DIR or ./memory.

from memkraft import MemKraft
mk = MemKraft("/path/to/memory")

Core Methods

Extraction & Classification

Search

Maintenance

Logging

Debug Hypothesis Tracking

Memory Snapshots & Time Travel

⌨️ CLI Reference

memkraft <command> [options]

Commands

Raw Input ──▶ Extract ──▶ Classify ──▶ Forge ──▶ Compound Knowledge
     ▲            │                                      │
     │        Confidence                                 │
     │        Applicability                              │
     │                                                   │
     └──── Feedback Loop ◄── Brain-first recall ◄───────┘
                              maintained by Dream Cycle + Health Check

How It Works

Zero dependencies. Built entirely from Python stdlib: re for NER, difflib for fuzzy search, json for structured data, pathlib for file ops. No vector DB, no LLM calls at runtime, no framework lock-in.

Compiled Truth + Timeline. Every entity has two layers: a mutable Compiled Truth (current state) and an append-only Timeline with [Source:] tags. You get both "what we know now" and "how we got here."

Auto-Extract pipeline. Multi-stage NER: English Title Case → Korean particle stripping → Chinese surname detection (100 surnames) → Japanese surname detection (85 surnames) → fact extraction (X is/was/leads Y) → stopword filtering (806 KR/CN/JP stopwords).

Goal-weighted re-ranking (Conway SMS). agentic_search("X", context="meeting prep") and agentic_search("X", context="investment analysis") return different rankings from the same data. Memory type, confidence, and applicability conditions all factor into scoring.

Feedback loop. --file-back files search results back into entity timelines. Each query makes future queries richer - compound interest for memory.

Health Check. 5 assertions: (1) source attribution, (2) no orphan facts, (3) no duplicates, (4) inbox freshness, (5) no unresolved conflicts. Returns a pass rate and letter grade (A/B/C/D).

Memory Directory Structure

memory/
├── .memkraft/           # Internal state (index.json, timestamps)
├── sessions/            # Structured event logs (YYYY-MM-DD.jsonl)
├── RESOLVER.md          # Classification decision tree (MECE)
├── TEMPLATES.md         # Page templates with tier labels
├── CONFLICTS.md         # Auto-generated conflict report
├── open-loops.md        # Unresolved items hub
├── fact-registry.md     # Cross-domain numeric/date facts
├── YYYY-MM-DD.md        # Daily notes
├── entities/            # People, companies, concepts (Tier: recall)
├── live-notes/          # Persistent tracking targets (Tier: core)
├── decisions/           # Decision records with rationale
├── originals/           # Captured verbatim - no paraphrasing
├── inbox/               # Quick capture before classification
├── tasks/               # Work-in-progress context
├── meetings/            # Briefs and notes
└── debug/               # Debug sessions (DEBUG-YYYYMMDD-HHMMSS.md)

⚖️ Comparison

Choose MemKraft when: you want portable, git-friendly, zero-dependency memory that works with any agent framework, offline, forever.

Choose something else when: you need semantic/vector search, graph traversal, or a full agent runtime with virtual context management.

🏆 Reproducing LongMemEval Results

MemKraft achieves 98.0% on LongMemEval (LLM-as-judge, oracle subset, 3-run semantic majority vote). Single-run performance: 96–98% (non-deterministic at inference level — sampling, not memory).

Score measured on v1.0.2; v2.6.0 is regression-free with 1168 tests passing and is API-compatible with the benchmark harness.

Comparison vs prior SOTA:

• MemKraft (v1.0.2 measurement) — 98.0% (LLM-judge, oracle 50, 3-run majority)
• MemPalace — 96.6%
• MEMENTO/MS — 90.8%

Setup

git clone https://github.com/seojoonkim/memkraft
cd memkraft
pip install -e ".[bench]"

Run

cd benchmarks/longmemeval

# Single run (96% typical)
MODEL="claude-sonnet-4-6" \
  ANTHROPIC_API_KEY="your-key" \
  TAG="myrun" \
  python3 run.py 50 oracle

# LLM-as-judge scoring
MODEL="claude-sonnet-4-6" \
  ANTHROPIC_API_KEY="your-key" \
  python3 llm_judge.py

# 3-run majority vote (98% typical)
MODEL="claude-sonnet-4-6" \
  ANTHROPIC_API_KEY="your-key" \
  python3 run_majority_vote.py

Notes

• Dataset: LongMemEval oracle subset (50 questions)
• Judge: LLM-as-judge (claude-sonnet-4-6) — semantic matching, not string match
• 98% = 3-run semantic majority vote result
• Single run: 96~100% depending on inference sampling
• Reproducibility note: Variance comes from LLM inference sampling, not from MemKraft itself. Memory storage and retrieval are deterministic.

🆙 Staying Up To Date

MemKraft ships an opt-in self-upgrade flow so agents (and humans) never silently drift behind PyPI:

memkraft doctor --check-updates   # 🟢 up to date / 🟡 update available / 🔴 PyPI unreachable
memkraft selfupdate               # pip install -U memkraft when newer
memkraft selfupdate --dry-run     # check only

Classic still works:

pip install -U memkraft

For agents: add memkraft doctor --check-updates to your weekly skill or heartbeat — if it reports 🟡, ask the human before running memkraft selfupdate. Never auto-upgrade without explicit consent.

For maintainers: pushing a vX.Y.Z git tag triggers .github/workflows/release.yml, which builds, verifies (twine check), publishes to PyPI, and cuts a GitHub Release. Requires a PYPI_API_TOKEN repo secret — add it at Settings → Secrets and variables → Actions.

Highlights from recent releases. Full history: CHANGELOG.md.

v2.6.0 (current)

• auto_tier — recommend core / recall / archival from (recency, frequency, importance); dry_run=True by default.
• fact_type on fact_add — episodic / semantic / procedural taxonomy with silent contradiction detection.
• 1-hop graph neighbor expansion for counting-style queries (how many, list all).
• 1168 tests passing; zero breaking changes from 2.5.x.

v2.5.0

• Hybrid search upgraded to exact + IDF + fuzzy + BM25.
• Smarter ranking on multi-token queries; better recall for short answers.

v2.4.0

• Cross-entity link graph hardened; faster link_scan, more reliable backlinks index.
• Performance improvements on large memory directories.

v2.3.x

• Watchdog-based memkraft watch stability fixes.
• Doctor health hints; richer --check-updates output.

v2.0.0

• Major API consolidation around the register → tune → recall → decide loop.
• Bitemporal facts, tier labels, reversible decay, link graph become first-class.
• Zero breaking changes from 0.9.x — see MIGRATION.md.

v1.1.0 — Autonomous Memory Management

flush → compact → digest self-managing lifecycle. See 🤖 Autonomous Memory Management above for details.

v1.0.0 — Self-Improvement Loop

prompt_register / prompt_eval / prompt_evidence / convergence_check make tuning a first-class, auditable workflow.

🤝 Contributing

PRs welcome. See CONTRIBUTING.md.

📄 License

MIT - use it however you want.

🙏 Appendix: Inspirations & Credits

MemKraft stands on the shoulders of giants. These projects and ideas shaped our approach:

"If I have seen further, it is by standing on the shoulders of giants."

Thank you to all these creators for sharing their work openly. MemKraft exists because of you.