{ "markdown": "\"image\"\n\n# Memory Kernel\n\n\n\n`Memory Kernel` is a small local memory layer for AI agents.\n\nIt helps you save useful things such as decisions, constraints, tasks, facts, and notes in a local SQLite database, then pull back only the few memories that matter for the current task.\n\nPublished package name on PyPI: `amormorri-memory-kernel`\nCLI command after install: `memory-kernel`\n\nPractical guide in Ukrainian:\n[docs/OPERATING_GUIDE_UK.md](docs/OPERATING_GUIDE_UK.md)\n\nRelease notes:\n[CHANGELOG.md](CHANGELOG.md)\n\n## Contents\n\n- [What It Does](#what-it-does)\n- [Start In 5 Minutes](#start-in-5-minutes)\n- [Typical Workflow](#typical-workflow)\n- [Which Command To Use](#which-command-to-use)\n - Write: [`remember`](#remember), [`ingest`](#ingest)\n - Read: [`search`](#search), [`context`](#context), [`wake-up`](#wake-up), [`stats`](#stats)\n - Inspect / edit: [`list`](#list), [`show`](#show), [`update`](#update), [`delete`](#delete)\n - Lifecycle: [`forget` / `restore`](#forget--restore), [`revise`](#revise), [`decay`](#decay)\n - Maintain: [`completion`](#completion), [`verify`](#verify)\n - Backup: [`export`](#export), [`import`](#import)\n- [Use With An LLM (MCP)](#use-with-an-llm-mcp)\n- [How It Works](#how-it-works)\n - [Data Flow](#data-flow)\n - [Component Diagram](#component-diagram)\n - [Memory Record Schema](#memory-record-schema)\n - [Ukrainian Inflection Bridging](#ukrainian-inflection-bridging)\n- [Why It Stays Lightweight](#why-it-stays-lightweight)\n- [Who It Is For](#who-it-is-for)\n- [Project Status](#project-status)\n- [Native Accelerator](#native-accelerator)\n- [Feedback](#feedback)\n\n## What It Does\n\nIn plain English, Memory Kernel does 4 things:\n\n1. Stores memory locally on your machine.\n2. Keeps memory structured enough to stay useful.\n3. Finds relevant records without a heavy vector stack.\n4. Builds a small context pack instead of dumping everything into the prompt.\n\nThis project is not trying to create a magical black-box memory. It is trying to create a memory layer you can inspect, control, export, and trust.\n\n## Start In 5 Minutes\n\nIf you just want to try it, do this:\n\n```powershell\npip install amormorri-memory-kernel\nmemory-kernel init\nmemory-kernel remember --scope my.project --kind decision --title \"Keep memory local\" --content \"We store memory on the user's machine.\"\nmemory-kernel search \"memory local\"\nmemory-kernel export --format json --output exports\\memory.json\n```\n\nWhat happened there:\n\n1. `init` created a local database.\n2. `remember` saved one clear memory.\n3. `search` fetched it back.\n4. `export` created a backup file you can move or restore later.\n\nIf you are using the repository instead of PyPI:\n\n```powershell\npip install -e .[dev]\n```\n\n## Typical Workflow\n\nMost people will use it like this:\n\n1. Save one precise memory with `remember`.\n2. Feed raw notes or transcripts with `ingest`.\n3. Before an agent run, fetch only what matters with `search`, `context`, or `wake-up`.\n4. Inspect, fix, or remove single records with `show`, `update`, or `delete`.\n5. Periodically export the database for backup.\n6. Restore it elsewhere with `import`.\n\n## Which Command To Use\n\n### `remember`\n\nUse `remember` when you already know exactly what should be saved.\n\nGood examples:\n\n- a decision\n- a rule\n- a user preference\n- a project constraint\n\n```powershell\nmemory-kernel remember --scope project.alpha --kind decision --title \"Use SQLite FTS5\" --content \"We use SQLite FTS5 for local retrieval.\"\n```\n\n### `ingest`\n\nUse `ingest` when you have raw text and want the system to split it into structured memories.\n\nGood examples:\n\n- meeting notes\n- a transcript\n- a rough planning document\n- an agent session log\n\n```powershell\nmemory-kernel ingest --scope project.alpha --file notes.txt --source sprint-review --tags planning transcript\n```\n\nAdd `--dry-run` to preview the segments and inferred kinds/titles/tags without writing to the database. Useful before committing a long file.\n\n```powershell\nmemory-kernel ingest --scope project.alpha --file notes.txt --dry-run\nmemory-kernel ingest --scope project.alpha --text \"...\" --dry-run --json\n```\n\nAdd `--interactive` for a guided flow that prompts for scope, source, tags, and the text itself, then shows a preview and asks for confirmation before saving. Helpful for first-time users or for ad-hoc captures from the terminal without remembering the flag names.\n\n```powershell\nmemory-kernel ingest --interactive\n```\n\n### `search`\n\nUse `search` when you want a few relevant exact memories for a query.\n\n```powershell\nmemory-kernel search \"context budget\"\n```\n\n### `context`\n\nUse `context` when you want a compact pack for an agent prompt.\n\n```powershell\nmemory-kernel context \"How do we keep memory cheap?\" --budget-chars 700\n```\n\n### `wake-up`\n\nUse `wake-up` when you want a small \"hot memory\" pack before a task starts.\n\n```powershell\nmemory-kernel wake-up --budget-chars 500\n```\n\n### `stats`\n\nUse `stats` when you want to see database size and whether the native accelerator is active.\n\n```powershell\nmemory-kernel stats\nmemory-kernel stats --since 7d\nmemory-kernel stats --since 2026-04-01\n```\n\n`--since` adds recent-activity counts (created and updated since the cutoff) plus a per-kind breakdown for the window. Accepts either a relative form like `7d` or an ISO date.\n\n### `list`\n\nUse `list` to browse recent memories (most recently updated first) with optional filters.\n\n```powershell\nmemory-kernel list\nmemory-kernel list --scope project.alpha --limit 50\nmemory-kernel list --kind decision --tags rust memory\nmemory-kernel list --json\n```\n\nDefault limit is 20. The output shows `id`, `kind/scope`, `title`, and the timestamps so you can pipe ids into `show`/`update`/`delete`.\n\n### `show`\n\nUse `show` when you have a memory id (printed by `search`, `remember --json`, or `export`) and want the full record.\n\n```powershell\nmemory-kernel show --id 9f1e8c0a4b2d4e7f8a1b2c3d4e5f6a7b\nmemory-kernel show --id 9f1e8c0a4b2d4e7f8a1b2c3d4e5f6a7b --json\n```\n\n### `update`\n\nUse `update` to fix specific fields on an existing memory without re-importing the whole database.\n\n```powershell\nmemory-kernel update --id 9f1e... --title \"Renamed memory\" --importance 0.95\nmemory-kernel update --id 9f1e... --tags rust memory acceleration\nmemory-kernel update --id 9f1e... --tags\n```\n\nOnly the fields you pass change. Pass `--tags` with no values to clear tags. Pass `--kind`, `--importance`, or `--certainty` to revise validation-bound fields.\n\n### `delete`\n\nUse `delete` to drop a memory you saved by mistake or that no longer applies.\n\n```powershell\nmemory-kernel delete --id 9f1e8c0a4b2d4e7f8a1b2c3d4e5f6a7b\n```\n\nThe command exits non-zero if the id does not exist, so wrap it in shell logic if you script around it.\n\n### `forget` / `restore`\n\n`delete` removes a memory permanently. When you only want it out of recall but kept for safety, use `forget` — a soft-archive. Archived memories disappear from `search`, `context`, `wake-up`, and `list`, but the data stays and `restore` brings it back.\n\n```powershell\nmemory-kernel forget --id 9f1e...\nmemory-kernel restore --id 9f1e...\nmemory-kernel list --include-archived # see archived/superseded memories\n```\n\nRe-saving the same memory with `remember`/`ingest` also resurrects it automatically.\n\n### `revise`\n\nWhen a new memory replaces an old one, record the relationship with `revise`: the old memory is marked superseded (hidden from recall, kept for history with a pointer to its replacement).\n\n```powershell\nmemory-kernel revise --id --supersedes \n```\n\nThis keeps memory self-curating: stale decisions fade out of recall as newer ones take their place, instead of piling up as contradictory noise.\n\n### `decay`\n\n`decay` applies a forgetting curve: it auto-archives memories that are old, rarely recalled, and low-value, so the store and your recall stay lean over time. Each memory has a retention score built from its importance, how often it has been recalled (reinforcement), and how long since it was last seen (time decay).\n\n```powershell\nmemory-kernel decay --dry-run # preview what would fade\nmemory-kernel decay # apply (archives, recoverable)\nmemory-kernel decay --min-age-days 60 --max-access 0 --scope project.alpha\n```\n\nOnly `note` and `fact` memories are eligible — `decision`, `constraint`, `task`, and `preference` are never decayed. Archiving is the soft, recoverable kind, so `restore` and `list --include-archived` still reach faded memories. This is the heart of the project's thesis: spend the budget on what matters, let trivia fade.\n\n### `completion`\n\nUse `completion` to print a shell completion script for `memory-kernel`. The script is generated dynamically from the current parser, so it stays in sync as commands are added.\n\n```powershell\nmemory-kernel completion powershell | Out-File -Encoding utf8 $PROFILE.CurrentUserAllHosts -Append\nmemory-kernel completion bash > ~/.local/share/bash-completion/completions/memory-kernel\n```\n\nAfter installing, `memory-kernel ` shows all subcommands; `memory-kernel remember --` lists flags for that command; `memory-kernel remember --kind ` cycles through valid `kind` values.\n\n### `verify`\n\nUse `verify` to check that the database is internally consistent: schema version is current, derived columns (`stems_text`, `fingerprint`) match the source content, and the FTS5 index row count matches the memories table.\n\n```powershell\nmemory-kernel verify\nmemory-kernel verify --repair\nmemory-kernel verify --repair --json\n```\n\nWithout `--repair`, exit code is `0` when healthy and `1` when issues are found. With `--repair`, mismatches are recomputed in-place and the FTS index is rebuilt if its row count drifted; exit code is `0` if everything was fixed.\n\nUseful after restoring from a manual backup, after editing the database with raw SQL, or as a periodic sanity check in CI.\n\n### `export`\n\nUse `export` for backup, migration, or inspection.\n\n```powershell\nmemory-kernel export --format json --output exports\\memory.json\nmemory-kernel export --scope project.alpha --format jsonl --output exports\\project-alpha.jsonl\n```\n\n### `import`\n\nUse `import` to restore a previous export.\n\n```powershell\nmemory-kernel import --file exports\\memory.json\nmemory-kernel import --file exports\\project-alpha.jsonl\n```\n\n`import` is idempotent for the same exported records because it upserts by memory `id`.\n\n## Use With An LLM (MCP)\n\nMemory Kernel ships an [MCP](https://modelcontextprotocol.io) server so an LLM can save and recall memories itself during a session. It works with Claude Desktop, Claude Code, Cursor, and any other MCP client, over stdio.\n\nInstall with the MCP extra:\n\n```powershell\npip install \"amormorri-memory-kernel[mcp]\"\n```\n\nRun it directly to check it starts:\n\n```powershell\nmemory-kernel-mcp --db .memory-kernel\\memory.db\n# or via the main CLI:\nmemory-kernel serve-mcp --db-path .memory-kernel\\memory.db\n```\n\nThen register it with your client. For **Claude Desktop** (`claude_desktop_config.json`):\n\n```json\n{\n \"mcpServers\": {\n \"memory-kernel\": {\n \"command\": \"memory-kernel-mcp\",\n \"env\": { \"MEMORY_KERNEL_DB\": \"C:\\\\Users\\\\you\\\\.memory-kernel\\\\memory.db\" }\n }\n }\n}\n```\n\nFor **Claude Code / Cursor** (`.mcp.json` in the project root):\n\n```json\n{\n \"mcpServers\": {\n \"memory-kernel\": {\n \"command\": \"memory-kernel-mcp\",\n \"args\": [\"--db\", \"${workspaceFolder}/.memory-kernel/memory.db\"]\n }\n }\n}\n```\n\nThe server exposes seven tools:\n\n| Tool | Purpose | Read-only |\n|------|---------|-----------|\n| `memory_remember` | Save one precise memory | no (dedup-merge, non-destructive) |\n| `memory_ingest` | Split raw text into structured memories | no |\n| `memory_forget` | Soft-archive a memory (recoverable) | no (reversible) |\n| `memory_search` | Find relevant memories (Ukrainian forms bridged) | yes |\n| `memory_build_context` | Budget-limited context pack for a prompt | yes |\n| `memory_wake_up` | Hot-memory pack for session start | yes |\n| `memory_list` | Browse recent memories | yes |\n| `memory_stats` | Store statistics | yes |\n\n`memory_forget` is exposed because it is reversible — an agent can let a stale memory fade, and a human can `restore` it from the CLI. Truly destructive edits (`delete`, `update`, `revise`) are deliberately **not** exposed over MCP: an agent can add, recall, and soft-forget, but only you can permanently rewrite or remove.\n\nTools take flat parameters, so the model sees `scope`, `kind`, `title`, … directly. Verify the whole protocol round-trip any time with `python scripts/mcp_smoke.py`, and see [docs/REAL_AI_TEST.md](docs/REAL_AI_TEST.md) for a hand-test script to run on a real model.\n\n## How It Works\n\nThe core idea is simple:\n\n1. Store exact text locally.\n2. Search cheaply with `SQLite` and `FTS5`.\n3. Rank results deterministically instead of fuzzily.\n4. Return a small context pack with a hard character budget.\n\nThat is how Memory Kernel reduces both blur and overhead.\n\n### Data Flow\n\n```mermaid\nflowchart TD\n A[Raw input: note, transcript, command] --> B{Entry mode}\n B -->|remember| C[One validated memory]\n B -->|ingest| D[Split into memory candidates]\n D --> E[Infer kind, title, summary, tags, importance, certainty]\n E --> F[Duplicate-aware upsert]\n C --> F\n F --> G[(SQLite + FTS5)]\n G --> H[Search candidates]\n H --> I[Deterministic ranking]\n I --> J[Top memories]\n J --> K[Context pack with hard size limit]\n K --> L[LLM or AI agent]\n```\n\n### Component Diagram\n\n```mermaid\nflowchart LR\n U[User or Agent] --> CLI[CLI or Python API]\n CLI --> STORE[MemoryStore]\n STORE --> DB[(SQLite + FTS5)]\n STORE --> ACCEL[Optional Rust accelerator]\n STORE --> PACK[Context pack builder]\n PACK --> MODEL[LLM]\n```\n\n### Memory Record Schema\n\n```text\nMemoryRecord\n|- scope\n|- kind\n|- title\n|- summary\n|- content\n|- tags\n|- source\n|- importance\n|- certainty\n|- access_count\n|- created_at\n|- updated_at\n\\- last_accessed_at\n```\n\n### Leaner Context Packs\n\nWhen building a `context` or `wake-up` pack, Memory Kernel skips a memory whose content closely overlaps one already included (token-overlap above a threshold). Under the same character budget, the pack then carries more distinct facts and less repetition — directly lowering the redundant context handed to the model. Tune or disable per call with `dedup_threshold` (1.0 disables).\n\n### Ukrainian Inflection Bridging\n\nSearch bridges Ukrainian morphology in two layers:\n\n1. **Suffix stemming on the query** expands each term to a short stem (`вирішили` → `виріш*`). This finds `вирішили`, `вирішення`, `вирішує`, `вирішена` — anything sharing the same prefix.\n2. **Deep stemming of stored content** (suffix + prefix stripping) lives in a separate `stems_text` column inside the FTS5 index. The query also matches against deep stems exactly (`stems_text:ріш`). This bridges across different prefixes, so a search for `рішення` also finds `вирішили` and `невирішене` — they all collapse to the same `ріш` stem.\n\nStored title/summary/content/tags stay exact, so fingerprints, deduplication, ranking, and export all remain deterministic. Only the FTS5 index gains a derived `stems_text` column.\n\nDisable with:\n\n```powershell\n$env:MEMORY_KERNEL_DISABLE_STEMMER=1\n```\n\nDisabling only affects the query side. `stems_text` keeps being populated on writes so toggling the env back on does not require a rebuild.\n\n## Why It Stays Lightweight\n\nMemory Kernel stays small on purpose:\n\n- `SQLite` + `FTS5` instead of a mandatory vector database\n- deterministic ranking instead of fuzzy always-on retrieval\n- duplicate-aware updates instead of endless memory growth\n- hard context budgets instead of large prompt dumps\n- optional `Rust` acceleration only where it actually helps\n\nFor embedded Python usage, `MemoryStore` keeps a long-lived SQLite connection for throughput. Prefer `with MemoryStore(...) as store:` or call `store.close()` when you are done.\n\n## Who It Is For\n\nThis is a good fit when you want:\n\n- local-first memory on your own machine\n- clear records you can inspect\n- small, predictable retrieval\n- easy export and restore\n\nThis is a weaker fit when you want:\n\n- a fully hosted managed platform\n- zero local setup\n- fully automatic cleanup of messy notes with no review\n\n## Project Status\n\nCurrent stage: working alpha.\n\nAlready working:\n\n- package layout\n- CLI\n- tests\n- export and import\n- optional Rust accelerator\n- Python fallback without Rust\n\nStill in progress:\n\n- prebuilt wheels for major platforms\n- a simpler guided ingest flow\n- even lighter onboarding for non-technical users\n\n## Native Accelerator\n\nThe Python implementation is the stable default.\n\nIf you want lower overhead on ingest and heuristic hot paths, build the optional `Rust` module:\n\n```powershell\n.\\scripts\\build_native.ps1\n```\n\nAfter that, `memory-kernel stats` will show whether `accelerator: rust` is active.\n\nYou can benchmark the current hot paths with:\n\n```powershell\npython .\\scripts\\benchmark_ingest.py\npython .\\scripts\\benchmark_upsert.py\n```\n\nExperimental native ranking is available for profiling:\n\n```powershell\n$env:MEMORY_KERNEL_EXPERIMENTAL_NATIVE_RANK=1\n```\n\n## License\n\nApache License 2.0 (see [LICENSE](LICENSE) and [NOTICE](NOTICE)). Versions up to and including 0.3.1 were released under the Unlicense and remain available under those terms; all later versions are Apache-2.0. Contributions require a DCO sign-off — see [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Feedback\n\nIssue tracker:\nhttps://github.com/Artem362/memory-kernel/issues\n\nIssue template chooser:\nhttps://github.com/Artem362/memory-kernel/issues/new/choose\n\nThere is also a first-run feedback template in:\n`.github/ISSUE_TEMPLATE/first-run-feedback.yml`\n\nThe most useful early report includes:\n\n- where you installed from\n- your OS and Python version\n- the exact command you ran\n- what you expected\n- what actually happened\n", "bytes": 18025, "sha": "3631266273a5b0221e664c80253be6e5732c0a4ea6d5de013dc5d0301041966c", "repo_slug": "artem362/memory-kernel", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_artem362_memory_kernel_45ce811e/readme" }