Memory Kernel

Memory Kernel

Memory Kernel is a small local memory layer for AI agents.

It 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.

Published package name on PyPI: amormorri-memory-kernel CLI command after install: memory-kernel

Practical guide in Ukrainian: docs/OPERATING_GUIDE_UK.md

Release notes: CHANGELOG.md

Contents

• What It Does
• Start In 5 Minutes
• Typical Workflow
• Which Command To Use
• Write: remember, ingest
• Read: search, context, wake-up, stats
• Inspect / edit: list, show, update, delete
• Lifecycle: forget / restore, revise, decay
• Maintain: completion, verify
• Backup: export, import
• Use With An LLM (MCP)
• How It Works
• Data Flow
• Component Diagram
• Memory Record Schema
• Ukrainian Inflection Bridging
• Why It Stays Lightweight
• Who It Is For
• Project Status
• Native Accelerator
• Feedback

What It Does

In plain English, Memory Kernel does 4 things:

1. Stores memory locally on your machine.
2. Keeps memory structured enough to stay useful.
3. Finds relevant records without a heavy vector stack.
4. Builds a small context pack instead of dumping everything into the prompt.

This 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.

Start In 5 Minutes

If you just want to try it, do this:

pip install amormorri-memory-kernel

memory-kernel init memory-kernel remember --scope my.project --kind decision --title "Keep memory local" --content "We store memory on the user's machine." memory-kernel search "memory local" memory-kernel export --format json --output exports\memory.json

What happened there:

1. init created a local database.
2. remember saved one clear memory.
3. search fetched it back.
4. export created a backup file you can move or restore later.

If you are using the repository instead of PyPI:

pip install -e .[dev]

Typical Workflow

Most people will use it like this:

1. Save one precise memory with remember.
2. Feed raw notes or transcripts with ingest.
3. Before an agent run, fetch only what matters with search, context, or wake-up.
4. Inspect, fix, or remove single records with show, update, or delete.
5. Periodically export the database for backup.
6. Restore it elsewhere with import.

Which Command To Use

remember

Use remember when you already know exactly what should be saved.

Good examples:

• a decision
• a rule
• a user preference
• a project constraint

memory-kernel remember --scope project.alpha --kind decision --title "Use SQLite FTS5" --content "We use SQLite FTS5 for local retrieval."

ingest

Use ingest when you have raw text and want the system to split it into structured memories.

Good examples:

• meeting notes
• a transcript
• a rough planning document
• an agent session log

memory-kernel ingest --scope project.alpha --file notes.txt --source sprint-review --tags planning transcript

Add --dry-run to preview the segments and inferred kinds/titles/tags without writing to the database. Useful before committing a long file.

memory-kernel ingest --scope project.alpha --file notes.txt --dry-run

memory-kernel ingest --scope project.alpha --text "..." --dry-run --json

Add --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.

memory-kernel ingest --interactive

search

Use search when you want a few relevant exact memories for a query.

memory-kernel search "context budget"

context

Use context when you want a compact pack for an agent prompt.

memory-kernel context "How do we keep memory cheap?" --budget-chars 700

wake-up

Use wake-up when you want a small "hot memory" pack before a task starts.

memory-kernel wake-up --budget-chars 500

stats

Use stats when you want to see database size and whether the native accelerator is active.

memory-kernel stats

memory-kernel stats --since 7d memory-kernel stats --since 2026-04-01

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

list

Use list to browse recent memories (most recently updated first) with optional filters.

memory-kernel list

memory-kernel list --scope project.alpha --limit 50 memory-kernel list --kind decision --tags rust memory memory-kernel list --json

Default limit is 20. The output shows id, kind/scope, title, and the timestamps so you can pipe ids into show/update/delete.

show

Use show when you have a memory id (printed by search, remember --json, or export) and want the full record.

memory-kernel show --id 9f1e8c0a4b2d4e7f8a1b2c3d4e5f6a7b

memory-kernel show --id 9f1e8c0a4b2d4e7f8a1b2c3d4e5f6a7b --json

update

Use update to fix specific fields on an existing memory without re-importing the whole database.

memory-kernel update --id 9f1e... --title "Renamed memory" --importance 0.95

memory-kernel update --id 9f1e... --tags rust memory acceleration memory-kernel update --id 9f1e... --tags

Only the fields you pass change. Pass --tags with no values to clear tags. Pass --kind, --importance, or --certainty to revise validation-bound fields.

delete

Use delete to drop a memory you saved by mistake or that no longer applies.

memory-kernel delete --id 9f1e8c0a4b2d4e7f8a1b2c3d4e5f6a7b

The command exits non-zero if the id does not exist, so wrap it in shell logic if you script around it.

forget / restore

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.

memory-kernel forget --id 9f1e...

memory-kernel restore --id 9f1e... memory-kernel list --include-archived # see archived/superseded memories

Re-saving the same memory with remember/ingest also resurrects it automatically.

revise

When 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).

memory-kernel revise --id <new-id> --supersedes <old-id>

This keeps memory self-curating: stale decisions fade out of recall as newer ones take their place, instead of piling up as contradictory noise.

decay

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).

memory-kernel decay --dry-run          # preview what would fade

memory-kernel decay # apply (archives, recoverable) memory-kernel decay --min-age-days 60 --max-access 0 --scope project.alpha

Only 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.

completion

Use 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.

memory-kernel completion powershell | Out-File -Encoding utf8 $PROFILE.CurrentUserAllHosts -Append

memory-kernel completion bash > ~/.local/share/bash-completion/completions/memory-kernel

After installing, memory-kernel shows all subcommands; memory-kernel remember -- lists flags for that command; memory-kernel remember --kind cycles through valid kind values.

verify

Use 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.

memory-kernel verify

memory-kernel verify --repair memory-kernel verify --repair --json

Without --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.

Useful after restoring from a manual backup, after editing the database with raw SQL, or as a periodic sanity check in CI.

export

Use export for backup, migration, or inspection.

memory-kernel export --format json --output exports\memory.json

memory-kernel export --scope project.alpha --format jsonl --output exports\project-alpha.jsonl

import

Use import to restore a previous export.

memory-kernel import --file exports\memory.json

memory-kernel import --file exports\project-alpha.jsonl

import is idempotent for the same exported records because it upserts by memory id.

Use With An LLM (MCP)

Memory Kernel ships an MCP 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.

Install with the MCP extra:

pip install "amormorri-memory-kernel[mcp]"

Run it directly to check it starts:

memory-kernel-mcp --db .memory-kernel\memory.db

or via the main CLI:

memory-kernel serve-mcp --db-path .memory-kernel\memory.db

Then register it with your client. For Claude Desktop (claude_desktop_config.json):

{

"mcpServers": { "memory-kernel": { "command": "memory-kernel-mcp", "env": { "MEMORY_KERNEL_DB": "C:\\Users\\you\\.memory-kernel\\memory.db" } } } }

For Claude Code / Cursor (.mcp.json in the project root):

{

"mcpServers": { "memory-kernel": { "command": "memory-kernel-mcp", "args": ["--db", "${workspaceFolder}/.memory-kernel/memory.db"] } } }

The server exposes seven tools:

| `m