[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-1634":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":13,"stars7d":13,"stars30d":16,"stars90d":15,"forks30d":15,"starsTrendScore":17,"compositeScore":18,"rankGlobal":9,"rankLanguage":9,"license":19,"archived":20,"fork":20,"defaultBranch":21,"hasWiki":22,"hasPages":20,"topics":23,"createdAt":9,"pushedAt":9,"updatedAt":24,"readmeContent":25,"aiSummary":26,"trendingCount":15,"starSnapshotCount":15,"syncStatus":13,"lastSyncTime":27,"discoverSource":28},1634,"memkraft","seojoonkim\u002Fmemkraft","seojoonkim","Ultimate zero-dependency compound knowledge system for AI agents. Auto-extract, classify, search, and maintain memory in plain Markdown.",null,"Python",188,23,2,8,0,5,6,49.64,"MIT License",false,"main",true,[],"2026-06-12 04:00:10","\u003Cimg src=\"assets\u002Fmemkraft-banner.webp\" alt=\"MemKraft - Zero-dependency compound memory for AI agents\" width=\"100%\">\n\n# MemKraft 🧠\n\n> **Bitemporal memory × empirical tuning: the first self-improvement ledger for AI agents.**\n> Your agent's accountable past, in plain Markdown.\n\n**🏆 LongMemEval 98.0% — #1 on open-source agent long-term memory benchmarks**\n_(Surpasses MemPalace 96.6%, MEMENTO by Microsoft 90.8% · LLM-as-judge · oracle 50 · 3-run semantic majority)_\n\n**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.**\n\n> **Plain Markdown source-of-truth · zero deps · zero keys · zero LLM calls inside MemKraft.**\n> In 30 seconds: `pipx install memkraft && memkraft init && memkraft agents-hint claude-code`\n\n\u003Cdiv align=\"center\">\n\n\u003Cbr>\n\n[![PyPI][pypi-badge]][pypi-url]\n[![Python][python-badge]][pypi-url]\n[![License][license-badge]][license-url]\n[![Tests][tests-badge]](#)\n[![Dependencies][deps-badge]][pypi-url]\n\n[pypi-badge]: https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fv\u002Fmemkraft?style=for-the-badge&color=blue\n[python-badge]: https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fpython-3.9%2B-blue?style=for-the-badge\n[license-badge]: https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-MIT-green?style=for-the-badge\n[tests-badge]: https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Ftests-1168%20passed-brightgreen?style=for-the-badge\n[deps-badge]: https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fdependencies-zero-brightgreen?style=for-the-badge\n[pypi-url]: https:\u002F\u002Fpypi.org\u002Fproject\u002Fmemkraft\u002F\n[license-url]: LICENSE\n\n\u003Cbr>\n\n\u003C\u002Fdiv>\n\n[![PyPI](https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fv\u002Fmemkraft.svg)](https:\u002F\u002Fpypi.org\u002Fproject\u002Fmemkraft\u002F)\n[![Python](https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fpyversions\u002Fmemkraft.svg)](https:\u002F\u002Fpypi.org\u002Fproject\u002Fmemkraft\u002F)\n[![Downloads](https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fdm\u002Fmemkraft.svg)](https:\u002F\u002Fpypi.org\u002Fproject\u002Fmemkraft\u002F)\n[![License: MIT](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-yellow.svg)](LICENSE)\n\n---\n\n## 📖 Table of Contents\n\n- [⚡ Quickstart (30s)](#-quickstart-30s)\n- [🎯 Why MemKraft?](#-why-memkraft)\n- [🧩 Features](#-features)\n- [🍳 Real-world Recipes](#-real-world-recipes)\n- [🔬 Specialized Features](#-specialized-features)\n- [📚 API Reference](#-api-reference)\n- [⌨️ CLI Reference](#-cli-reference)\n- [🏗️ Architecture](#-architecture)\n- [⚖️ Comparison](#-comparison)\n- [🏆 Reproducing LongMemEval](#-reproducing-longmemeval-results)\n- [🆙 Staying Up To Date](#-staying-up-to-date)\n- [📝 Changelog](#-changelog)\n- [🤝 Contributing](#-contributing)\n- [📄 License](#-license)\n- [🙏 Appendix: Inspirations & Credits](#-appendix-inspirations--credits)\n\n\u003Cbr>\n\n## ⚡ Quickstart (30s)\n\n```bash\npip install memkraft\nmemkraft init                   # → creates .\u002Fmemory\u002F with RESOLVER, TEMPLATES, entities\u002F, ...\nmemkraft agents-hint claude-code >> AGENTS.md   # your agent is now memory-aware\n```\n\n### Or scaffold a full project\n\n```bash\nmemkraft init --template claude-code   # CLAUDE.md + memory\u002F + examples\nmemkraft init --template cursor        # .cursorrules + memory\u002F\nmemkraft init --template mcp           # claude_desktop_config snippet + memory\u002F\nmemkraft init --template rag           # retrieval-focused structure\nmemkraft init --template minimal       # just memory\u002Fentities\u002F\nmemkraft templates list                # see all presets\n```\n\nTemplates are **idempotent** — re-running `init --template X` never overwrites your edits.\n\nOr in Python:\n\n```python\nfrom memkraft import MemKraft\nmk = MemKraft(\".\u002Fmemory\"); mk.init()\nmk.track(\"Simon Kim\", entity_type=\"person\", source=\"news\")\nmk.update(\"Simon Kim\", info=\"Launched MemKraft 0.8.1\", source=\"PyPI\")\nmk.search(\"MemKraft\")\n```\n\nThat's it. Your agent now has persistent memory as plain markdown files.\nNo API keys. No database. No config. Just `.md` files you own.\n\n### Optional extras\n\n```bash\npip install 'memkraft[mcp]'      # + MCP server  (`python -m memkraft.mcp`)\npip install 'memkraft[watch]'    # + auto-reindex on save (`memkraft watch`)\npip install 'memkraft[all]'      # everything\n```\n\n### Connect Any Agent in 30 Seconds\n\n`memkraft agents-hint \u003Ctarget>` prints copy-paste-ready integration snippets:\n\n```bash\nmemkraft agents-hint claude-code   # → CLAUDE.md \u002F AGENTS.md block\nmemkraft agents-hint openclaw      # → AGENTS.md block for ОpenClaw\nmemkraft agents-hint cursor        # → .cursorrules block\nmemkraft agents-hint openai        # → Custom GPT \u002F function-calling schema\nmemkraft agents-hint mcp           # → claude_desktop_config.json snippet\nmemkraft agents-hint langchain     # → LangChain StructuredTool wrappers\n```\n\nPaste the output. Done. Or pipe it straight into your config:\n\n```bash\nmemkraft agents-hint claude-code >> AGENTS.md\n```\n\nSee [`examples\u002F`](examples\u002F) for runnable variants.\n\n\u003Cbr>\n\n## 🎯 Why MemKraft?\n\n### What Makes MemKraft Different\n\n|                        | **MemKraft**   | Mem0        | Letta    |\n|------------------------|----------------|-------------|----------|\n| Dependencies           | **0**          | many        | many     |\n| API key required       | **No**         | Yes         | Yes      |\n| Source of truth        | Plain `.md`    | Cloud\u002FDB    | DB       |\n| Local-first            | ✅             | —           | —        |\n| Git-friendly           | ✅             | —           | —        |\n\n### API overview (14 public methods)\n\n| API | Since | Role |\n|-----|-------|------|\n| `track` | 0.5 | Start tracking an entity |\n| `update` | 0.5 | Append information to an entity |\n| `search` | 0.5 | Hybrid search (exact + IDF + fuzzy + BM25) |\n| `tier_set` | 0.8 | Set tier: `core` \u002F `recall` \u002F `archival` |\n| `fact_add` | 0.8 | Record a bitemporal fact (`fact_type`: `episodic` \u002F `semantic` \u002F `procedural` since **2.6**) |\n| `log_event` | 0.8 | Log a timestamped event |\n| `decision_record` | 0.9 | Capture a decision with rationale |\n| `evidence_first` | 0.9 | Retrieve evidence before acting |\n| `prompt_register` | **1.0** | Register a prompt\u002Fskill as an entity |\n| `prompt_eval` | **1.0** | Record one tuning iteration |\n| `prompt_evidence` | **1.0** | Cite past tuning results |\n| `convergence_check` | **1.0** | Auto-judge convergence |\n| `auto_tier` | **2.6** | Recommend `core` \u002F `recall` \u002F `archival` from `(recency, frequency, importance)`; `dry_run=True` by default |\n| `cache_stats` | **2.7** | Inspect search cache hit\u002Fmiss\u002Feviction counters and current generation |\n\nAlso new in **2.6**: silent contradiction detection on `fact_add`, plus 1-hop graph neighbor expansion for counting-style queries (`how many`, `list all`).\n\nNew 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\u002F50 mixed workload — raw numbers in `benchmarks\u002Fv2.7.0-bench-result.json`. Zero breaking changes.\n\nSelf-improvement loop: **register → tune → recall → decide**, every step auditable and time-travelable. See [MIGRATION.md](.\u002FMIGRATION.md) for upgrading from 0.9.x (zero breaking changes).\n\n### The 1.0 Self-Improvement Loop\n\nRegister a prompt\u002Fskill, record iterations, cite past evidence, and let\nMemKraft auto-judge when to stop tuning — all in plain Markdown, no LLM\ncalls inside MemKraft:\n\n```python\nfrom memkraft import MemKraft\nmk = MemKraft(\".\u002Fmemory\")\n\n# 1. register a prompt\u002Fskill as a first-class entity\nmk.prompt_register(\n    \"my-skill\",\n    path=\"skills\u002Fmy-skill\u002FSKILL.md\",\n    owner=\"zeon\",\n    tags=[\"tuning\"],\n)\n\n# 2. record each empirical iteration (host agent dispatches the run\n#    — MemKraft only persists the report)\nmk.prompt_eval(\n    \"my-skill\",\n    iteration=1,\n    scenarios=[{\n        \"name\": \"parallel-dispatch\",\n        \"description\": \"3 subagents at once\",\n        \"requirements\": [{\"item\": \"all return\", \"critical\": True}],\n    }],\n    results=[{\n        \"scenario\": \"parallel-dispatch\",\n        \"success\": True, \"accuracy\": 85,\n        \"tool_uses\": 5, \"duration_ms\": 2000,\n        \"unclear_points\": [\"schema missing\"],\n        \"discretion\": [],\n    }],\n)\n\n# 3. cite past iterations before the next run\nmk.prompt_evidence(\"my-skill\", \"accuracy regression\")\n\n# 4. stop when the last N iterations stabilise\nverdict = mk.convergence_check(\"my-skill\", window=2)\n# -> {\"converged\": False, \"reason\": \"insufficient-iters\",\n#     \"iterations_checked\": [1],\n#     \"suggested_next\": \"patch-and-iterate\", ...}\n```\n\nEach call leaves an auditable trail on disk: a decision record per\niteration, an incident when unclear points pile up, and wiki-links\nbetween iterations. Upgrade is zero-breaking from 0.9.x — see\n[MIGRATION.md](.\u002FMIGRATION.md).\n\n\u003Cbr>\n## 🧩 Features\n\n### Ingestion & Extraction\n\n| Feature | Description |\n|---------|-------------|\n| **Auto-extract** | Pipe any text in, get entities + facts out. Regex-based NER for EN, KR, CN, JP - no LLM calls. |\n| **CJK detection** | 806 stopwords, 100 Chinese surnames, 85 Japanese surnames, Korean particle stripping. |\n| **Cognify pipeline** | Routes `inbox\u002F` items to the right directory. Recommend-only by default - `--apply` to move. |\n| **Fact registry** | Extracts currencies, percentages, dates, quantities into a cross-domain index. |\n| **Originals capture** | Save raw text verbatim - no paraphrasing. |\n| **Confidence levels** | Tag facts as `verified` \u002F `experimental` \u002F `hypothesis`. Dream Cycle warns untagged facts. |\n| **Applicability conditions** | `--when \"condition\" --when-not \"condition\"` - facts get `When:` \u002F `When NOT:` metadata. |\n\n### Search & Retrieval\n\n| Feature | Description |\n|---------|-------------|\n| **Fuzzy search** | `difflib.SequenceMatcher`-based. Works offline, zero setup. |\n| **Brain-first lookup** | Searches entities → notes → decisions → meetings. Stops after sufficient high-relevance results. |\n| **Agentic search** | Multi-hop: decompose query → search → traverse `[[wiki-links]]` → re-rank by tier\u002Frecency\u002Fconfidence\u002Fapplicability. |\n| **Goal-weighted re-ranking** | Conway SMS: same query with different `--context` produces different rankings. |\n| **Feedback loop** | `--file-back`: search results auto-filed back to entity timelines (compound interest for memory). |\n| **Progressive disclosure** | 3-level query: L1 index (~50 tokens) → L2 section headers → L3 full file. |\n| **Backlinks** | `[[entity-name]]` cross-references. See every page that references an entity. |\n| **Link suggestions** | Auto-suggest missing `[[wiki-links]]` based on known entity names. |\n\n### Structure & Organization\n\n| Feature | Description |\n|---------|-------------|\n| **Compiled Truth + Timeline** | Dual-layer entity model: mutable current state + append-only audit trail with `[Source:]` tags. |\n| **Memory tiers** | Core \u002F Recall \u002F Archival - explicit context window priority. `promote` to reclassify. |\n| **Memory type classification** | 8 types: identity, belief, preference, relationship, skill, episodic, routine, transient. |\n| **Type-aware decay** | Identity memories decay 10x slower than routine memories. Differential decay multipliers. |\n| **RESOLVER.md** | MECE classification tree - every piece of knowledge has exactly one destination. |\n| **Source attribution** | Every fact tagged with `[Source: who, when, how]`. Enforced by Dream Cycle. |\n| **Dialectic synthesis** | Auto-detect contradictory facts during `extract`, tag `[CONFLICT]`, generate `CONFLICTS.md`. |\n| **Conflict resolution** | `resolve-conflicts --strategy newest|confidence|keep-both|prompt`. |\n| **Live Notes** | Persistent tracking for people and companies. Auto-incrementing updates + timeline. |\n\n### Maintenance & Audit\n\n| Feature | Description |\n|---------|-------------|\n| **Dream Cycle** | Nightly auto-maintenance: missing sources, thin pages, duplicates, inbox age, bloated pages, daily notes. |\n| **Debug Hypothesis Tracking** | OBSERVE → HYPOTHESIZE → EXPERIMENT → CONCLUDE flow. Track hypotheses, evidence, rejections. Auto-switch warning after 2 failures. Search past sessions to avoid repeating failed approaches. |\n| **Health Check** | 5 self-diagnostic assertions: source attribution, orphan facts, duplicates, inbox freshness, unresolved conflicts. Pass rate % + health score (A\u002FB\u002FC\u002FD). |\n| **Memory decay** | Older, unaccessed memories naturally decay - type-aware differential curves. |\n| **Fact dedup** | Detects and merges duplicate facts across entities. |\n| **Auto-summarize** | Condenses bloated pages while preserving key information. |\n| **Diff tracking** | See exactly what changed since the last Dream Cycle. |\n| **Open loop tracking** | Finds all pending \u002F TODO \u002F FIXME items across memory. |\n\n### Logging & Reflection\n\n| Feature | Description |\n|---------|-------------|\n| **Session logging** | JSONL event trail with tags, importance, entity, task, and decision fields. |\n| **Daily retrospective** | Auto-generated Well \u002F Bad \u002F Next from session events + file changes. |\n| **Decision distillation** | Scans events and notes for decision candidates. EN + KR keyword matching. |\n| **Meeting briefs** | One command compiles entity info, timeline, open threads, and a pre-meeting checklist. |\n\n### Debugging\n\n| Feature | Description |\n|---------|-------------|\n| ✅ **Debug Hypothesis Tracking** | OBSERVE→HYPOTHESIZE→EXPERIMENT→CONCLUDE loop with persistent failure memory. |\n\n\u003Cbr>\n\n## 🍳 Real-world Recipes\n\n```bash\nmemkraft init\nmemkraft extract \"Simon Kim is the CEO of Hashed in Seoul.\" --source \"news\"\nmemkraft brief \"Simon Kim\"\nmemkraft doctor                          # 🟢\u002F🟡\u002F🔴 health check with fix hints\nmemkraft doctor --fix --yes              # auto-repair missing structure (create-only, never deletes)\nmemkraft stats --export json             # workspace stats for CI dashboards\nmemkraft mcp doctor                      # validate MCP server readiness\nmemkraft mcp test                        # remember→search→recall smoke test\n```\n\nMCP (Claude Desktop \u002F Cursor) setup: see [`docs\u002Fmcp-setup.md`](docs\u002Fmcp-setup.md).\n\n### Python Usage\n\n```python\nfrom memkraft import MemKraft\n\nmk = MemKraft(\"\u002Fpath\u002Fto\u002Fmemory\")\nmk.init()  # returns {\"created\": [...], \"exists\": [...], \"base_dir\": \"...\"}\n\n# Extract entities & facts from text\nmk.extract_conversations(\"Simon Kim is the CEO of Hashed.\", source=\"news\")\n\n# Track an entity\nmk.track(\"Simon Kim\", entity_type=\"person\", source=\"news\")\nmk.update(\"Simon Kim\", info=\"Launched MemKraft\", source=\"X\u002F@simonkim_nft\")\n\n# Search with fuzzy matching\nresults = mk.search(\"venture capital\", fuzzy=True)\n\n# Agentic multi-hop search with context-aware re-ranking\nresults = mk.agentic_search(\n    \"who is the CEO of Hashed\",\n    context=\"crypto investment research\",  # Conway SMS: same query, different context → different ranking\n    file_back=True,  # feedback loop: results auto-filed back to entity timelines\n)\n\n# Run health check (5 self-diagnostic assertions)\nreport = mk.health_check()\n# → {\"pass_rate\": 80.0, \"health_score\": \"A\", ...}\n\n# Dream Cycle - nightly maintenance\nmk.dream(dry_run=True)\n```\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>More CLI examples - 6 daily patterns that cover 90% of use\u003C\u002Fb>\u003C\u002Fsummary>\n\n\u003Cbr>\n\n```bash\n# 1. Extract & Track - auto-detect entities from any text\nmemkraft extract \"Simon Kim is the CEO of Hashed in Seoul.\" --source \"news\"\nmemkraft extract \"Revenue grew 85% YoY\" --confidence verified --when \"bull market\"\nmemkraft track \"Simon Kim\" --type person --source \"X\u002F@simonkim_nft\"\nmemkraft update \"Simon Kim\" --info \"Launched MemKraft\" --source \"X\u002F@simonkim_nft\"\n\n# 2. Search & Recall - find anything in your memory\nmemkraft search \"venture capital\" --fuzzy\nmemkraft search \"Seoul VC\" --file-back           # feedback loop: auto-file to timelines\nmemkraft lookup \"Simon\" --brain-first\nmemkraft agentic-search \"who is the CEO of Hashed\" --context \"meeting prep\"\n\n# 3. Meeting Prep - compile all context before a meeting\nmemkraft brief \"Simon Kim\"\nmemkraft brief \"Simon Kim\" --file-back            # record brief generation in timeline\nmemkraft links \"Simon Kim\"\n\n# 4. Ingest & Classify - inbox → structured pages (safe by default)\nmemkraft cognify            # recommend-only; add --apply to move files\nmemkraft detect \"Jack Ma and 马化腾 discussed AI\" --dry-run\n\n# 5. Log & Reflect - structured audit trail\nmemkraft log --event \"Deployed v0.3\" --tags deploy --importance high\nmemkraft retro              # daily Well \u002F Bad \u002F Next retrospective\n\n# 6. Maintain & Heal - Dream Cycle keeps memory healthy\nmemkraft health-check       # 5 assertions → pass rate + health score (A\u002FB\u002FC\u002FD)\nmemkraft dream --dry-run    # nightly: sources, duplicates, bloated pages\nmemkraft resolve-conflicts --strategy confidence  # resolve contradictory facts\nmemkraft diff               # what changed since last maintenance?\nmemkraft open-loops         # find all unresolved items\n\n# 7. Debug Hypothesis Tracking - \"Debugging is Memory\"\nmemkraft debug start \"API returns 500 on POST \u002Fusers\"\nmemkraft debug hypothesis \"Database connection timeout\"\nmemkraft debug evidence \"DB pool healthy\" --result contradicts\nmemkraft debug reject --reason \"DB is fine\"\nmemkraft debug hypothesis \"Request validation missing\"\nmemkraft debug evidence \"Empty POST triggers 500\" --result supports\nmemkraft debug confirm\nmemkraft debug end \"Added request body validation\"\nmemkraft debug search-rejected \"timeout\"  # avoid past mistakes\n```\n\n\u003C\u002Fdetails>\n\n\u003Cbr>\n## 🔬 Specialized Features\n\nThis section gathers features that deserve a closer look: time-travel snapshots, multi-agent context plumbing, autonomous memory lifecycle, and scientific debugging.\n\n### 📸 Memory Snapshots & Time Travel (v0.5.1)\n\n| Feature | Description |\n|---------|-------------|\n| **Snapshot** | Create a point-in-time manifest of all memory files (hash, size, summary, sections, fact count, link count). Optionally embed full content. |\n| **Snapshot List** | List all saved snapshots, newest first, with labels and metadata. |\n| **Snapshot Diff** | Compare two snapshots (or snapshot vs live state). Shows added, removed, modified, unchanged files with byte deltas. |\n| **Time Travel** | Search memory *as it was* at a past snapshot. Answer \"what did I know about X on March 1st?\" |\n| **Entity Timeline** | Track how a specific entity evolved across all snapshots — new, modified, unchanged, deleted states. |\n\n```python\nfrom memkraft import MemKraft\n\nmk = MemKraft(\"\u002Fpath\u002Fto\u002Fmemory\")\n\n# Take a snapshot before a big operation\nsnap = mk.snapshot(label=\"before-migration\", include_content=True)\n\n# ... time passes, memory changes ...\n\n# What changed?\ndiff = mk.snapshot_diff(snap[\"snapshot_id\"])  # vs live state\n# → {added: [...], removed: [...], modified: [...], unchanged_count: 42}\n\n# Search memory as it was at that snapshot\nresults = mk.time_travel(\"venture capital\", snapshot_id=snap[\"snapshot_id\"])\n\n# How did an entity evolve over time?\ntimeline = mk.snapshot_entity(\"Simon Kim\")\n# → [{snapshot_id, timestamp, fact_count, size, change_type: \"new\"}, ...]\n```\n\n### 🧠 Channel Context Memory + Task Continuity + Agent Working Memory (v0.5.4)\n\n| Feature | Description |\n|---------|-------------|\n| **Channel Context Memory** | Per-channel context persistence. Save\u002Fload\u002Fupdate context keyed by channel ID (e.g. `telegram-46291309`). Stored in `.memkraft\u002Fchannels\u002F{channel_id}.json`. |\n| **Task Continuity Register** | Task lifecycle tracking with full history. `task_start` → `task_update` → `task_complete` + `task_history` + `task_list`. Each update stores timestamp + status + note. Stored in `.memkraft\u002Ftasks\u002F{task_id}.json`. |\n| **Agent Working Memory** | Per-agent persistent context. `agent_save` \u002F `agent_load` any working memory dict. Stored in `.memkraft\u002Fagents\u002F{agent_id}.json`. |\n| **`agent_inject()`** | **The key feature.** Merges agent working memory + channel context + task history into a single ready-to-inject prompt block. Use this to give sub-agents full situational awareness. |\n\n```python\nfrom memkraft import MemKraft\n\nmk = MemKraft(\"\u002Fpath\u002Fto\u002Fmemory\")\n\n# Save channel context\nmk.channel_save(\"telegram-46291309\", {\n    \"summary\": \"DM with Simon\",\n    \"recent_tasks\": [\"vibekai deploy\", \"memkraft v0.5.4\"],\n    \"preferences\": {\"language\": \"ko\"},\n})\n\n# Register a task\nmk.task_start(\"deploy-001\", \"Deploy vibekai to production\",\n              channel_id=\"telegram-46291309\", agent=\"zeon\")\nmk.task_update(\"deploy-001\", \"active\", \"vercel build passed\")\n\n# Save agent working memory\nmk.agent_save(\"zeon\", {\n    \"key_context\": \"Simon's AI assistant\",\n    \"active_tasks\": [\"deploy-001\"],\n    \"learned\": [\"always report completion\", \"no silence\"],\n})\n\n# Inject merged context block into a sub-agent instruction\nblock = mk.agent_inject(\"zeon\",\n                        channel_id=\"telegram-46291309\",\n                        task_id=\"deploy-001\")\nprint(block)\n# ## Agent Working Memory\n# - **key_context:** Simon's AI assistant\n# - **active_tasks:** deploy-001\n# ...\n# ## Channel Context\n# - **summary:** DM with Simon\n# ...\n# ## Task Context\n# - **Task:** Deploy vibekai to production\n# - **Status:** active\n# - **History:**\n#   - [2026-04-15T...] active: vercel build passed\n```\n\n### 🤖 Autonomous Memory Management (v1.1.0)\n\n> *\"Memory should manage itself.\"*\n\nMemory tends to grow without limit — agents add entries but rarely clean up.\nMemKraft 1.1.0 solves this with a self-managing lifecycle.\n\n#### The Problem\n- **Add-only pattern**: agents append to MEMORY.md every session, never prune\n- **Silent maintenance failures**: nightly cleanup crons fail without notice\n- **No lifecycle**: every memory entry treated equally, forever\n\n#### The Solution: flush → compact → digest\n\n```python\nfrom memkraft import MemKraft\nmk = MemKraft(base_dir=\"memory\u002F\")\n\n# 1. Import existing MEMORY.md → structured MemKraft data\nmk.flush(\"MEMORY.md\")\n\n# 2. Auto-archive old\u002Flow-priority items\nresult = mk.compact(max_chars=15000)\n# → {\"moved\": 47, \"freed_chars\": 89400, ...}\n\n# 3. Re-render MEMORY.md — always ≤ 15KB\nmk.digest(\"MEMORY.md\")\n# → {\"chars\": 11700, \"truncated\": False}\n\n# 4. Check memory health\nhealth = mk.health()\n# → {\"status\": \"healthy\", \"total_chars\": 11700, \"recommendations\": [...]}\n```\n\n#### Real-world result\nOur MEMORY.md grew to **153KB** (1,862 lines) over weeks of agent sessions.\nAfter `flush → compact → digest`: **11.7KB** (170 lines). **92% reduction.**\n\n#### Nightly self-cleanup recipe\n```python\n# Watch for real-time sync\nmk.watch(\"memory\u002F\", on_change=\"flush\", interval=300)\n\n# Or set a nightly schedule (requires: pip install memkraft[schedule])\nmk.schedule([\n    lambda: mk.compact(max_chars=15000),\n    lambda: mk.digest(\"MEMORY.md\"),\n], cron_expr=\"0 23 * * *\")\n```\n\n### 🐛 Debugging is Memory\n\nDebugging insights are too valuable to lose in scrollback. MemKraft treats the entire debug process as first-class memory.\n\n**The debug-hypothesis loop** - inspired by [Shen Huang's scientific debugging method](https:\u002F\u002Fgithub.com\u002FLichAmnesia\u002Flich-skills\u002Ftree\u002Fmain\u002Fskills\u002Fdebug-hypothesis):\n\n```\nOBSERVE → HYPOTHESIZE → EXPERIMENT → CONCLUDE\n    ↑                        |\n    |    rejected?           |\n    +←── next hypothesis ←───+\n    |\n    all rejected? → back to OBSERVE\n```\n\n- `mk.start_debug(\"bug description\")` - begin a tracked session\n- `mk.log_hypothesis(bug_id, \"theory\", \"evidence\")` - record each theory\n- `mk.log_evidence(bug_id, hyp_id, \"test result\", \"supports|contradicts\")` - track proof\n- `mk.reject_hypothesis(bug_id, hyp_id, \"reason\")` - mark failed approaches\n- `mk.confirm_hypothesis(bug_id, hyp_id)` - lock in the root cause\n- `mk.end_debug(bug_id, \"resolution\")` - close session, feed back to memory\n\n**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.\n\n\u003Cbr>\n## 📚 API Reference\n\n### `MemKraft(base_dir=None)`\n\nInitialize the memory system. If `base_dir` is not provided, uses `$MEMKRAFT_DIR` or `.\u002Fmemory`.\n\n```python\nfrom memkraft import MemKraft\nmk = MemKraft(\"\u002Fpath\u002Fto\u002Fmemory\")\n```\n\n### Core Methods\n\n| Method | Description |\n|--------|-------------|\n| `init(path=\"\")` | Create memory directory structure with all subdirectories and templates. |\n| `track(name, entity_type=\"person\", source=\"\")` | Start tracking an entity. Creates a live-note in `live-notes\u002F`. |\n| `update(name, info, source=\"manual\")` | Append new information to a tracked entity's timeline. |\n| `brief(name, save=False, file_back=False)` | Generate a meeting brief for an entity. `file_back=True` records the brief generation in the entity timeline. |\n| `promote(name, tier=\"core\")` | Change memory tier: `core` \u002F `recall` \u002F `archival`. |\n| `list_entities()` | List all tracked entities with their types. |\n\n### Extraction & Classification\n\n| Method | Description |\n|--------|-------------|\n| `extract_conversations(input_text, source=\"\", dry_run=False, confidence=\"experimental\", applicability=\"\")` | Extract entities and facts from text. `confidence`: `verified` \u002F `experimental` \u002F `hypothesis`. `applicability`: `\"When: X \\| When NOT: Y\"`. |\n| `detect(text, source=\"\", dry_run=False)` | Detect entities in text (EN\u002FKR\u002FCN\u002FJP). |\n| `cognify(dry_run=False, apply=False)` | Route inbox items to structured directories. Recommend-only by default. |\n| `extract_facts_registry(text=\"\")` | Extract numeric\u002Fdate facts into cross-domain index. |\n| `detect_conflicts(entity_name, new_fact, source=\"\")` | Check for contradictory facts and tag with `[CONFLICT]`. |\n| `resolve_conflicts(strategy=\"newest\", dry_run=False)` | Resolve conflicts. Strategies: `newest`, `confidence`, `keep-both`, `prompt`. |\n| `classify_memory_type(text)` | Classify text into one of 8 memory types. |\n\n### Search\n\n| Method | Description |\n|--------|-------------|\n| `search(query, fuzzy=False)` | Search memory files. Returns list of `{file, score, context, line}`. |\n| `agentic_search(query, max_hops=2, json_output=False, context=\"\", file_back=False)` | Multi-hop search with query decomposition, link traversal, and goal-weighted re-ranking. `context` enables Conway SMS reconstructive ranking. `file_back` enables the feedback loop. |\n| `lookup(query, json_output=False, brain_first=False, full=False)` | Brain-first lookup: stop early on high-relevance hits unless `full=True`. |\n| `query(query=\"\", level=1, recent=0, tag=\"\", date=\"\")` | Progressive disclosure: L1=index, L2=sections, L3=full. |\n| `links(name)` | Show backlinks to an entity (`[[wiki-links]]`). |\n\n### Maintenance\n\n| Method | Description |\n|--------|-------------|\n| `dream(date=None, dry_run=False, resolve_conflicts=False)` | Run Dream Cycle. 6 health checks + optional conflict resolution. |\n| `health_check()` | Run 5 self-diagnostic assertions. Returns `{pass_rate, health_score, assertions}`. |\n| `decay(days=90, dry_run=False)` | Flag stale facts. Type-aware: identity decays 10x slower than routine. |\n| `dedup(dry_run=False)` | Find and merge duplicate facts. |\n| `summarize(name=None, max_length=500)` | Auto-summarize bloated entity pages. |\n| `diff()` | Show changes since last Dream Cycle. |\n| `open_loops(dry_run=False)` | Find unresolved items (TODO\u002FFIXME\u002Fpending). |\n| `build_index()` | Build memory index at `.memkraft\u002Findex.json`. |\n| `suggest_links()` | Suggest missing `[[wiki-links]]`. |\n\n### Logging\n\n| Method | Description |\n|--------|-------------|\n| `log_event(event, tags=\"\", importance=\"normal\", entity=\"\", task=\"\", decision=\"\")` | Log a session event to JSONL. |\n| `log_read(date=None)` | Read session events for a date. |\n| `retro(dry_run=False)` | Generate daily retrospective (Well \u002F Bad \u002F Next). |\n| `distill_decisions()` | Scan for decision candidates in events and notes. |\n\n### Debug Hypothesis Tracking\n\n| Method | Description |\n|--------|-------------|\n| `start_debug(bug_description)` | Start a new debug session. Returns `{bug_id, file, status}`. |\n| `log_hypothesis(bug_id, hypothesis, evidence=\"\", status=\"testing\")` | Log a hypothesis. Auto-increments ID (H1, H2, ...). |\n| `get_hypotheses(bug_id)` | Get all hypotheses for a debug session. |\n| `reject_hypothesis(bug_id, hypothesis_id, reason=\"\")` | Reject a hypothesis. Preserved permanently for future reference. |\n| `confirm_hypothesis(bug_id, hypothesis_id)` | Confirm a hypothesis. Feeds back into memory. |\n| `log_evidence(bug_id, hypothesis_id, evidence_text, result=\"neutral\")` | Log evidence. Result: `supports` \u002F `contradicts` \u002F `neutral`. |\n| `get_evidence(bug_id, hypothesis_id=\"\")` | Get evidence entries, optionally filtered by hypothesis. |\n| `end_debug(bug_id, resolution)` | End session with resolution. Auto-feeds to memory. |\n| `get_debug_status(bug_id)` | Get current session status and hypothesis counts. |\n| `debug_history(limit=10)` | List past debug sessions. |\n| `search_debug_sessions(query)` | Search past sessions by description\u002Fhypothesis\u002Fresolution. |\n| `search_rejected_hypotheses(query)` | Search rejected hypotheses — anti-pattern detector. |\n\n### Memory Snapshots & Time Travel\n\n| Method | Description |\n|--------|-------------|\n| `snapshot(label=\"\", include_content=False)` | Create a point-in-time snapshot of all memory files. Returns `{snapshot_id, timestamp, label, file_count, total_bytes, path}`. |\n| `snapshot_list()` | List all saved snapshots, newest first. |\n| `snapshot_diff(snapshot_a, snapshot_b=\"\")` | Compare two snapshots, or a snapshot vs live state. Returns `{added, removed, modified, unchanged_count}`. |\n| `time_travel(query, snapshot_id=\"\", date=\"\")` | Search memory as it was at a past snapshot. Supports search by snapshot ID or date. |\n| `snapshot_entity(name)` | Track how a specific entity evolved across all snapshots (new\u002Fmodified\u002Funchanged\u002Fdeleted). |\n\n\u003Cbr>\n\n## ⌨️ CLI Reference\n\n```\nmemkraft \u003Ccommand> [options]\n```\n\n### Commands\n\n| Command | Description |\n|---------|-------------|\n| `init [--path DIR]` | Initialize memory structure |\n| `extract TEXT [--source S] [--dry-run] [--confidence C] [--when W] [--when-not W]` | Auto-extract entities and facts |\n| `detect TEXT [--source S] [--dry-run]` | Detect entities in text (EN\u002FKR\u002FCN\u002FJP) |\n| `track NAME [--type T] [--source S]` | Start tracking an entity |\n| `update NAME --info INFO [--source S]` | Update a tracked entity |\n| `list` | List all tracked entities |\n| `brief NAME [--save] [--file-back]` | Generate meeting brief |\n| `promote NAME [--tier T]` | Change memory tier (core\u002Frecall\u002Farchival) |\n| `search QUERY [--fuzzy] [--file-back]` | Search memory files |\n| `agentic-search QUERY [--max-hops N] [--json] [--context C] [--file-back]` | Multi-hop agentic search |\n| `lookup QUERY [--json] [--brain-first] [--full]` | Brain-first lookup |\n| `query [QUERY] [--level 1\\|2\\|3] [--recent N] [--tag T] [--date D]` | Progressive disclosure query |\n| `links NAME` | Show backlinks to an entity |\n| `cognify [--dry-run] [--apply]` | Process inbox into structured pages |\n| `log --event E [--tags T] [--importance I] [--entity E] [--task T] [--decision D]` | Log session event |\n| `log --read [--date D]` | Read session events |\n| `retro [--dry-run]` | Daily retrospective |\n| `distill-decisions` | Scan for decision candidates |\n| `health-check` | Run 5 self-diagnostic assertions → health score |\n| `dream [--date D] [--dry-run] [--resolve-conflicts]` | Run Dream Cycle (nightly maintenance) |\n| `resolve-conflicts [--strategy S] [--dry-run]` | Resolve fact conflicts |\n| `decay [--days N] [--dry-run]` | Flag stale facts |\n| `dedup [--dry-run]` | Find and merge duplicates |\n| `summarize [NAME] [--max-length N]` | Auto-summarize bloated pages |\n| `diff` | Show changes since last Dream Cycle |\n| `open-loops [--dry-run]` | Find unresolved items |\n| `index` | Build memory index |\n| `suggest-links` | Suggest missing wiki-links |\n| `extract-facts [TEXT]` | Extract numeric\u002Fdate facts |\n| `debug start DESC` | Start a new debug session (OBSERVE) |\n| `debug hypothesis TEXT [--bug-id ID] [--evidence E]` | Log a hypothesis (HYPOTHESIZE) |\n| `debug evidence TEXT [--bug-id ID] [--hypothesis-id H] [--result R]` | Log evidence (supports\u002Fcontradicts\u002Fneutral) |\n| `debug reject [--bug-id ID] [--hypothesis-id H] [--reason R]` | Reject current hypothesis |\n| `debug confirm [--bug-id ID] [--hypothesis-id H]` | Confirm current hypothesis |\n| `debug status [--bug-id ID]` | Show debug session status |\n| `debug history [--limit N]` | List past debug sessions |\n| `debug end RESOLUTION [--bug-id ID]` | End debug session (CONCLUDE) |\n| `debug search QUERY` | Search past debug sessions |\n| `debug search-rejected QUERY` | Search rejected hypotheses (anti-patterns) |\n| `snapshot [--label L] [--include-content]` | Create a point-in-time memory snapshot |\n| `snapshot-list` | List all saved snapshots (newest first) |\n| `snapshot-diff SNAP_A [SNAP_B]` | Compare two snapshots or snapshot vs live state |\n| `time-travel QUERY [--snapshot ID] [--date YYYY-MM-DD]` | Search memory as it was at a past snapshot |\n| `snapshot-entity NAME` | Show how an entity evolved across snapshots |\n| `selfupdate [--dry-run]` | Self-upgrade MemKraft via pip when newer version on PyPI |\n| `doctor [--check-updates]` | Health check; with `--check-updates` also reports PyPI version status |\n\n\u003Cbr>\n## 🏗️ Architecture\n\n```\nRaw Input ──▶ Extract ──▶ Classify ──▶ Forge ──▶ Compound Knowledge\n     ▲            │                                      │\n     │        Confidence                                 │\n     │        Applicability                              │\n     │                                                   │\n     └──── Feedback Loop ◄── Brain-first recall ◄───────┘\n                              maintained by Dream Cycle + Health Check\n```\n\n### How It Works\n\n**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.\n\n**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.\"\n\n**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\u002Fwas\u002Fleads Y`) → stopword filtering (806 KR\u002FCN\u002FJP stopwords).\n\n**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.\n\n**Feedback loop.** `--file-back` files search results back into entity timelines. Each query makes future queries richer - compound interest for memory.\n\n**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\u002FB\u002FC\u002FD).\n\n### Memory Directory Structure\n\n```\nmemory\u002F\n├── .memkraft\u002F           # Internal state (index.json, timestamps)\n├── sessions\u002F            # Structured event logs (YYYY-MM-DD.jsonl)\n├── RESOLVER.md          # Classification decision tree (MECE)\n├── TEMPLATES.md         # Page templates with tier labels\n├── CONFLICTS.md         # Auto-generated conflict report\n├── open-loops.md        # Unresolved items hub\n├── fact-registry.md     # Cross-domain numeric\u002Fdate facts\n├── YYYY-MM-DD.md        # Daily notes\n├── entities\u002F            # People, companies, concepts (Tier: recall)\n├── live-notes\u002F          # Persistent tracking targets (Tier: core)\n├── decisions\u002F           # Decision records with rationale\n├── originals\u002F           # Captured verbatim - no paraphrasing\n├── inbox\u002F               # Quick capture before classification\n├── tasks\u002F               # Work-in-progress context\n├── meetings\u002F            # Briefs and notes\n└── debug\u002F               # Debug sessions (DEBUG-YYYYMMDD-HHMMSS.md)\n```\n\n\u003Cbr>\n\n## ⚖️ Comparison\n\n| | **MemKraft** | **Mem0** | **Letta** |\n|---|:---:|:---:|:---:|\n| **Storage** | Plain Markdown | Vector + Graph DB | DB-backed |\n| **Dependencies** | Zero | Vector DB + API | DB + runtime |\n| **Offline \u002F git-friendly** | ✅ | ❌ | ❌ |\n| Auto-extract (EN\u002FKR\u002FCN\u002FJP) | ✅ | ✅ (LLM) | - |\n| Agentic search | ✅ | - | - |\n| Goal-weighted re-ranking | ✅ | - | - |\n| Feedback loop | ✅ | - | - |\n| Confidence levels | ✅ | - | - |\n| Health check | ✅ | - | - |\n| Conflict detection & resolution | ✅ | - | - |\n| Source attribution | Required | - | - |\n| Dream Cycle | ✅ | - | - |\n| Memory tiers | ✅ | - | ✅ |\n| Type-aware decay | ✅ | - | - |\n| Debug hypothesis tracking | ✅ | - | - |\n| Memory snapshots & time travel | ✅ | ❌ | ❌ |\n| Entity evolution timeline | ✅ | ❌ | ❌ |\n| Snapshot diff | ✅ | ❌ | ❌ |\n| **Semantic search** | ❌ | ✅ | - |\n| **Graph memory** | ❌ | ✅ | - |\n| **Self-editing memory** | ❌ | - | ✅ |\n| **Cost** | Free | Free tier + paid | Free |\n\n**Choose MemKraft when:** you want portable, git-friendly, zero-dependency memory that works with any agent framework, offline, forever.\n\n**Choose something else when:** you need semantic\u002Fvector search, graph traversal, or a full agent runtime with virtual context management.\n\n\u003Cbr>\n\n## 🏆 Reproducing LongMemEval Results\n\nMemKraft achieves **98.0%** on [LongMemEval](https:\u002F\u002Fgithub.com\u002Fxiaowu0162\u002FLongMemEval) (LLM-as-judge, oracle subset, 3-run semantic majority vote). Single-run performance: **96–98%** (non-deterministic at inference level — sampling, not memory).\n\n_Score measured on v1.0.2; v2.6.0 is regression-free with **1168 tests passing** and is API-compatible with the benchmark harness._\n\n**Comparison vs prior SOTA:**\n- MemKraft (v1.0.2 measurement) — **98.0%** (LLM-judge, oracle 50, 3-run majority)\n- MemPalace — 96.6%\n- MEMENTO\u002FMS — 90.8%\n\n### Setup\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fseojoonkim\u002Fmemkraft\ncd memkraft\npip install -e \".[bench]\"\n```\n\n### Run\n\n```bash\ncd benchmarks\u002Flongmemeval\n\n# Single run (96% typical)\nMODEL=\"claude-sonnet-4-6\" \\\n  ANTHROPIC_API_KEY=\"your-key\" \\\n  TAG=\"myrun\" \\\n  python3 run.py 50 oracle\n\n# LLM-as-judge scoring\nMODEL=\"claude-sonnet-4-6\" \\\n  ANTHROPIC_API_KEY=\"your-key\" \\\n  python3 llm_judge.py\n\n# 3-run majority vote (98% typical)\nMODEL=\"claude-sonnet-4-6\" \\\n  ANTHROPIC_API_KEY=\"your-key\" \\\n  python3 run_majority_vote.py\n```\n\n### Notes\n\n- **Dataset:** LongMemEval oracle subset (50 questions)\n- **Judge:** LLM-as-judge (claude-sonnet-4-6) — semantic matching, not string match\n- **98%** = 3-run semantic majority vote result\n- **Single run:** 96~100% depending on inference sampling\n- **Reproducibility note:** Variance comes from LLM inference sampling, not from MemKraft itself. Memory storage and retrieval are deterministic.\n\n\u003Cbr>\n\n## 🆙 Staying Up To Date\n\nMemKraft ships an opt-in self-upgrade flow so agents (and humans) never silently drift behind PyPI:\n\n```bash\nmemkraft doctor --check-updates   # 🟢 up to date \u002F 🟡 update available \u002F 🔴 PyPI unreachable\nmemkraft selfupdate               # pip install -U memkraft when newer\nmemkraft selfupdate --dry-run     # check only\n```\n\nClassic still works:\n\n```bash\npip install -U memkraft\n```\n\n**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.\n\n**For maintainers:** pushing a `vX.Y.Z` git tag triggers `.github\u002Fworkflows\u002Frelease.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`.\n\n\u003Cbr>\n## 📝 Changelog\n\nHighlights from recent releases. Full history: [CHANGELOG.md](CHANGELOG.md).\n\n### v2.6.0 (current)\n\n- **`auto_tier`** — recommend `core` \u002F `recall` \u002F `archival` from `(recency, frequency, importance)`; `dry_run=True` by default.\n- **`fact_type`** on `fact_add` — `episodic` \u002F `semantic` \u002F `procedural` taxonomy with silent contradiction detection.\n- **1-hop graph neighbor expansion** for counting-style queries (`how many`, `list all`).\n- **1168 tests** passing; zero breaking changes from 2.5.x.\n\n### v2.5.0\n\n- Hybrid search upgraded to **exact + IDF + fuzzy + BM25**.\n- Smarter ranking on multi-token queries; better recall for short answers.\n\n### v2.4.0\n\n- Cross-entity link graph hardened; faster `link_scan`, more reliable backlinks index.\n- Performance improvements on large memory directories.\n\n### v2.3.x\n\n- Watchdog-based `memkraft watch` stability fixes.\n- Doctor health hints; richer `--check-updates` output.\n\n### v2.0.0\n\n- Major API consolidation around the **register → tune → recall → decide** loop.\n- Bitemporal facts, tier labels, reversible decay, link graph become first-class.\n- **Zero breaking changes** from 0.9.x — see [MIGRATION.md](.\u002FMIGRATION.md).\n\n### v1.1.0 — Autonomous Memory Management\n\n`flush → compact → digest` self-managing lifecycle. See **🤖 Autonomous Memory Management** above for details.\n\n### v1.0.0 — Self-Improvement Loop\n\n`prompt_register` \u002F `prompt_eval` \u002F `prompt_evidence` \u002F `convergence_check` make tuning a first-class, auditable workflow.\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>Earlier releases (v0.x — one-line summaries)\u003C\u002Fb>\u003C\u002Fsummary>\n\n\u003Cbr>\n\n- **v0.8.1** (2026-04-17) — `agents-hint` CLI, `examples\u002F`, `python -m memkraft.mcp`, `memkraft watch`, `memkraft doctor`. 515 tests.\n- **v0.8.0** (2026-04-17) — Bitemporal Fact Layer + Memory Tier Labels + Reversible Decay\u002FTombstone + Cross-Entity Link Graph. 492 tests.\n- **v0.7.0** (2026-04-15) — multi-agent: `channel_update` modes, task delegation, `agent_handoff`, channel task listing, task cleanup. 409 tests.\n- **v0.5.4** (2026-04-15) — Channel Context Memory + Task Continuity Register + Agent Working Memory + `agent_inject()`. 377 tests.\n- **v0.5.1** (2026-04-14) — Memory Snapshots & Time Travel: `snapshot` \u002F `snapshot_list` \u002F `snapshot_diff` \u002F `time_travel` \u002F `snapshot_entity`. 328 tests.\n- **v0.4.1** (2026-04-13) — README: Debugging is Memory section + Appendix (Inspirations & Credits).\n- **v0.4.0** (2026-04-13) — Debug Hypothesis Tracking: full OBSERVE→HYPOTHESIZE→EXPERIMENT→CONCLUDE loop, 2-fail auto-switch warning, `search_rejected_hypotheses()`. 277 tests.\n- **v0.3.0** (2026-04-13) — Query-to-Memory Feedback Loop (`--file-back`), Confidence Levels, Memory Health Assertions, Applicability Conditions. 198 tests.\n- **v0.2.0** (2026-04-12) — Goal-Weighted Reconstructive Memory (Conway SMS), Dialectic Synthesis, Memory Type Classification (8 types), Type-Aware Decay. 158 tests.\n- **v0.1.0** (2026-04-12) — Initial release: extract, detect, decay, dedup, summarize, agentic search, entity tracking, Dream Cycle, hybrid search. Zero dependencies.\n\nFull details for every release: [CHANGELOG.md](CHANGELOG.md).\n\n\u003C\u002Fdetails>\n\n\u003Cbr>\n\n## 🤝 Contributing\n\nPRs welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).\n\n\u003Cbr>\n\n## 📄 License\n\n[MIT](LICENSE) - use it however you want.\n\n---\n\n\u003Cdiv align=\"center\">\n\n**MemKraft** - *Agents don't learn. They search. Until now.*\n\n[GitHub](https:\u002F\u002Fgithub.com\u002Fseojoonkim\u002Fmemkraft) · [PyPI](https:\u002F\u002Fpypi.org\u002Fproject\u002Fmemkraft\u002F) · [Issues](https:\u002F\u002Fgithub.com\u002Fseojoonkim\u002Fmemkraft\u002Fissues)\n\n\u003C\u002Fdiv>\n\n\u003Cbr>\n\n## 🙏 Appendix: Inspirations & Credits\n\nMemKraft stands on the shoulders of giants. These projects and ideas shaped our approach:\n\n| Project | Inspiration | Link |\n|---------|------------|------|\n| **Karpathy auto-research** | Evidence-based autonomous research methodology | [Tweet](https:\u002F\u002Fx.com\u002Fkarpathy\u002Fstatus\u002F1906697764923920553) |\n| **Shen Huang debug-hypothesis** | Scientific debugging: hypothesis-driven, max 5-line experiments | [GitHub](https:\u002F\u002Fgithub.com\u002FLichAmnesia\u002Flich-skills\u002Ftree\u002Fmain\u002Fskills\u002Fdebug-hypothesis) · [Tweet](https:\u002F\u002Fx.com\u002FShenHuang_\u002Fstatus\u002F2043469166418735204) |\n| **Letta (MemGPT)** | Tiered memory architecture (core \u002F archival \u002F recall) | [GitHub](https:\u002F\u002Fgithub.com\u002Fletta-ai\u002Fletta) |\n| **mem0** | Agent memory extraction and retrieval patterns | [GitHub](https:\u002F\u002Fgithub.com\u002Fmem0ai\u002Fmem0) |\n| **Zep** | Temporal memory decay and entity extraction | [GitHub](https:\u002F\u002Fgithub.com\u002Fgetzep\u002Fzep) |\n| **MemoryWeaver** | Dialectic synthesis and memory reconstruction | [GitHub](https:\u002F\u002Fgithub.com\u002Fpchaganti\u002Fgx-memory-weaver) |\n| **Shubham Saboo's 6-agent system** | OpenClaw-based multi-agent + SOUL.md \u002F MEMORY.md pattern | [Article](https:\u002F\u002Fx.com\u002FSaboo_Shubham_\u002Farticle) |\n| **Karpathy llm-wiki** | Wiki-style structured knowledge for LLMs | [Tweet](https:\u002F\u002Fx.com\u002Fkarpathy\u002Fstatus\u002F2042079355925164424) |\n\n*\"If I have seen further, it is by standing on the shoulders of giants.\"*\n\nThank you to all these creators for sharing their work openly. MemKraft exists because of you.\n","MemKraft 是一个为AI代理设计的零依赖复合知识系统，能够自动提取、分类、搜索和维护以Markdown格式存储的记忆。其核心功能包括双向时间记忆、经验调优、以及在纯Markdown文件中实现记忆的自动提取与分类等，这些特性使得MemKraft在长时记忆管理方面表现出色，甚至超越了一些知名项目如Microsoft的MEMENTO。特别适用于需要长期记忆支持的人工智能应用场景，比如对话系统、虚拟助手等，通过提供一种简单而强大的方式来管理和利用历史数据，帮助提升AI代理的理解能力和响应质量。此外，MemKraft完全基于Python开发，易于安装和使用，不依赖任何外部服务或API调用，确保了高度的灵活性和安全性。","2026-06-11 02:45:10","CREATED_QUERY"]