Memory Kernel

Memory Kernel

Memory Kernel は、AI エージェント向けの小規模なローカルメモリレイヤーです。

判断、制約、タスク、事実、メモなどの役立つ情報をローカルの SQLite データベースに保存し、現在のタスクに関係するわずかなメモリだけを取り出せます。

PyPI で公開されているパッケージ名：amormorri-memory-kernel インストール後の CLI コマンド：memory-kernel

ウクライナ語の実用ガイド： docs/OPERATING_GUIDE_UK.md

リリースノート： CHANGELOG.md

目次

• できること
• 5 分で始める
• 一般的なワークフロー
• 使うコマンド
  • 書き込み：remember、ingest
  • 読み込み：search、context、wake-up、stats
  • 確認／編集：list、show、update、delete
  • ライフサイクル：forget / restore、revise、decay
  • メンテナンス：completion、verify
  • バックアップ：export、import
• LLM で使う（MCP）
• 仕組み
  • データフロー
  • コンポーネント図
  • メモリレコードのスキーマ
  • ウクライナ語の語形変化への対応
• 軽量さを保つ理由
• 対象ユーザー
• プロジェクトの状況
• ネイティブアクセラレーター
• フィードバック

できること

簡単に言うと、Memory Kernel は次の 4 つのことを行います。

1. メモリをマシン上にローカル保存します。
2. メモリを、役立つ状態を保てる程度に構造化します。
3. 大掛かりなベクトル処理スタックを使わずに、関連するレコードを見つけます。
4. プロンプトにすべてを詰め込むのではなく、小さなコンテキストパックを作成します。

このプロジェクトが目指すのは、魔法のようなブラックボックスのメモリではありません。確認、制御、エクスポートができ、信頼できるメモリレイヤーを作ることを目指しています。

5 分で始める

まず試してみたい場合は、次の手順を実行してください。

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

ここで行われたこと：

1. init でローカルデータベースを作成しました。
2. remember で明確なメモリを 1 件保存しました。
3. search でそのメモリを取り出しました。
4. export で、後から移動または復元できるバックアップファイルを作成しました。

PyPI ではなくリポジトリを使う場合：

pip install -e .[dev]

一般的なワークフロー

多くの場合、次のように使います。

1. remember で、正確なメモリを 1 件保存します。
2. ingest で、未加工のメモや文字起こしを取り込みます。
3. エージェントを実行する前に、search、context、または wake-up で必要な情報だけを取得します。
4. show、update、または delete で個別のレコードを確認、修正、削除します。
5. 定期的にデータベースをエクスポートしてバックアップします。
6. import で別の場所に復元します。

使うコマンド

remember

保存する内容がすでに明確な場合は、remember を使います。

適した例：

• 判断
• ルール
• ユーザーの好み
• プロジェクトの制約

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

ingest

未加工のテキストを構造化されたメモリに分割したい場合は、ingest を使います。

適した例：

• 会議メモ
• 文字起こし
• 概要段階の計画書
• エージェントのセッションログ

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

--dry-run を追加すると、データベースに書き込まずに、分割結果と推定された種類、タイトル、タグをプレビューできます。長いファイルを登録する前に便利です。

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

--interactive を追加すると、スコープ、ソース、タグ、テキストを順に入力するガイド付きフローが始まり、プレビューを表示して、保存前に確認を求めます。初めて使う場合や、フラグ名を覚えずにターミナルからその場で情報を記録したい場合に便利です。

memory-kernel ingest --interactive

search

クエリに関連する、正確なメモリをいくつか取得したい場合は、search を使います。

memory-kernel search "context budget"

context

エージェントのプロンプト向けにコンパクトなパックを作成したい場合は、context を使います。

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

wake-up

タスクの開始前に小さな「ホットメモリー」パックが必要な場合は、wake-up を使用します。

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

stats

データベースのサイズや、ネイティブアクセラレーターが有効かどうかを確認するには、stats を使用します。

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

--since を指定すると、期間内に作成・更新された件数と、種類ごとの内訳が追加されます。7d のような相対形式、または ISO 日付を指定できます。

list

最近のメモリーを（最終更新日時が新しい順に）閲覧するには、任意のフィルターを指定して list を使用します。

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

デフォルトの上限は 20 件です。出力には id、kind/scope、title、タイムスタンプが表示されるため、ID を show／update／delete に渡せます。

show

メモリー ID（search、remember --json、または export が出力したもの）があり、レコード全体を確認したい場合は、show を使用します。

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

update

データベース全体を再インポートせずに、既存のメモリーの特定のフィールドを修正するには、update を使用します。

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

変更されるのは、指定したフィールドのみです。タグをクリアするには、値を指定せずに --tags を渡します。検証対象のフィールドを修正するには、--kind、--importance、または --certainty を渡します。

delete

誤って保存したメモリーや、該当しなくなったメモリーを削除するには、delete を使用します。

memory-kernel delete --id 9f1e8c0a4b2d4e7f8a1b2c3d4e5f6a7b

ID が存在しない場合、コマンドはゼロ以外の終了コードを返すため、スクリプトから実行する場合はシェルの条件分岐で囲んでください。

forget / restore

delete はメモリーを完全に削除します。安全のために保持しつつ、想起の対象から外したい場合は、ソフトアーカイブである forget を使用します。アーカイブされたメモリーは search、context、wake-up、list から除外されますが、データは保持され、restore で元に戻せます。

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

同じメモリーを remember／ingest で再保存すると、自動的に復元されます。

revise

新しいメモリーが古いメモリーに取って代わる場合は、revise でその関係を記録します。古いメモリーは置き換え済みとしてマークされ、想起の対象からは外れますが、置き換え先を示す参照情報とともに履歴として保持されます。

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

これにより、メモリーは自己整理されるようになります。古い決定は、新しい決定に置き換わるにつれて想起されにくくなり、矛盾する情報として積み重なることはありません。

decay

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

対象となるのは note と fact のメモリーのみです。decision、constraint、task、preference は減衰しません。アーカイブは復元可能なソフトアーカイブなので、restore と list --include-archived で薄れていったメモリーにも引き続きアクセスできます。これがプロジェクトの基本理念です。重要なことに予算を使い、些細な情報は薄れさせます。

completion

memory-kernel のシェル補完スクリプトを出力するには、completion を使用します。スクリプトは現在のパーサーから動的に生成されるため、コマンドが追加されても同期が保たれます。

memory-kernel completion powershell | Out-File -Encoding utf8 $PROFILE.CurrentUserAllHosts -Append
memory-kernel completion bash > ~/.local/share/bash-completion/completions/memory-kernel

インストール後、memory-kernel <Tab><Tab> でサブコマンドがすべて表示されます。memory-kernel remember --<Tab> でそのコマンドのフラグが一覧表示され、memory-kernel remember --kind <Tab> で有効な kind の値を順に切り替えられます。

verify

データベースの整合性を確認するには、verify を使用します。スキーマのバージョンが最新であること、派生列（stems_text、fingerprint）が元の内容と一致していること、FTS5 インデックスの行数がメモリーテーブルと一致していることを確認します。

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

--repair を指定しない場合、正常なら終了コード 0、問題が見つかった場合は 1 になります。--repair を指定すると、不一致がその場で再計算され、FTS インデックスの行数にずれがあれば再構築されます。すべて修正された場合の終了コードは 0 です。

手動バックアップからの復元後、raw SQL でデータベースを編集した後、または CI で定期的に健全性を確認する際に便利です。

export

バックアップ、移行、または内容の確認には、export を使用します。

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

import

以前のエクスポートを復元するには、import を使用します。

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

import はメモリーの id に基づいてアップサートするため、同じエクスポート済みレコードをインポートしても結果は変わりません。

LLM で使用する（MCP）

Memory Kernel には、LLM がセッション中に自分で記憶を保存・呼び出せるようにする MCP サーバーが付属しています。stdio 経由で、Claude Desktop、Claude Code、Cursor、その他の MCP クライアントで動作します。

MCP 用の追加機能をインストールします。

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

直接実行して、起動することを確認します。

memory-kernel-mcp --db .memory-kernel\memory.db
# or via the main CLI:
memory-kernel serve-mcp --db-path .memory-kernel\memory.db

続いて、クライアントに登録します。Claude Desktop の場合（claude_desktop_config.json）：

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

Claude Code / Cursor の場合（プロジェクトルートの .mcp.json）：

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

サーバーは 7 つのツールを公開します。

ツール	用途	読み取り専用
memory_remember	正確な記憶を 1 件保存します	いいえ（重複を統合し、破壊的な変更は行いません）
memory_ingest	生テキストを構造化された記憶に分割します	いいえ
memory_forget	記憶をソフトアーカイブします（復元可能）	いいえ（元に戻せます）
memory_search	関連する記憶を検索します（ウクライナ語の語形にも対応）	はい
memory_build_context	プロンプト用に予算制限付きのコンテキストパックを作成します	はい
memory_wake_up	セッション開始用のホットメモリパックを作成します	はい
memory_list	最近の記憶を一覧表示します	はい
memory_stats	ストアの統計情報を表示します	はい

memory_forget は元に戻せるため公開されています。エージェントは古くなった記憶を薄れさせることができ、人間は CLI から restore で復元できます。完全に破壊的な編集（delete、update、revise）は、意図的に MCP 経由では公開していません。エージェントは追加、呼び出し、ソフト削除ができますが、恒久的な書き換えや削除ができるのはあなただけです。

ツールはフラットなパラメーターを受け取るため、モデルには scope、kind、title、…が直接表示されます。python scripts/mcp_smoke.py をいつでも実行してプロトコル全体の往復を検証できます。また、実際のモデルで実行する手動テスト用スクリプトについては、docs/REAL_AI_TEST.md を参照してください。

仕組み

基本的な考え方はシンプルです。

1. 正確なテキストをローカルに保存します。
2. SQLite と FTS5 で低コストに検索します。
3. あいまい検索ではなく、決定論的な方法で結果を順位付けします。
4. 文字数の上限を設けた小さなコンテキストパックを返します。

これにより、Memory Kernel は曖昧さとオーバーヘッドの両方を減らします。

データフロー

flowchart TD
    A[Raw input: note, transcript, command] --> B{Entry mode}
    B -->|remember| C[One validated memory]
    B -->|ingest| D[Split into memory candidates]
    D --> E[Infer kind, title, summary, tags, importance, certainty]
    E --> F[Duplicate-aware upsert]
    C --> F
    F --> G[(SQLite + FTS5)]
    G --> H[Search candidates]
    H --> I[Deterministic ranking]
    I --> J[Top memories]
    J --> K[Context pack with hard size limit]
    K --> L[LLM or AI agent]

コンポーネント図

flowchart LR
    U[User or Agent] --> CLI[CLI or Python API]
    CLI --> STORE[MemoryStore]
    STORE --> DB[(SQLite + FTS5)]
    STORE --> ACCEL[Optional Rust accelerator]
    STORE --> PACK[Context pack builder]
    PACK --> MODEL[LLM]

記憶レコードのスキーマ

MemoryRecord
|- scope
|- kind
|- title
|- summary
|- content
|- tags
|- source
|- importance
|- certainty
|- access_count
|- created_at
|- updated_at
\- last_accessed_at

より効率的なコンテキストパック

context または wake-up パックを作成する際、Memory Kernel は、すでに含まれている記憶と内容がよく似ている記憶（トークンの重複率がしきい値を超えるもの）をスキップします。同じ文字数上限でも、パックにはより多くの異なる事実が含まれ、重複が減ります。その結果、モデルに渡される冗長なコンテキストが直接減少します。dedup_threshold で呼び出しごとに調整または無効化できます（1.0 にすると無効になります）。

ウクライナ語の語形変化への対応

検索では、次の 2 層でウクライナ語の形態に対応します。

1. クエリに対する接尾辞ステミングにより、各語を短い語幹に展開します（вирішили → виріш*）。これにより、вирішили、вирішення、вирішує、вирішена など、同じ接頭部分を共有する語が見つかります。
2. 保存済みコンテンツに対する深層ステミング（接尾辞と接頭辞の除去）は、FTS5 インデックス内の別の stems_text 列に格納されます。クエリは深層ステムにも完全一致で照合されます（stems_text:ріш）。これにより異なる接頭辞をまたいで検索できるため、рішення を検索すると вирішили や невирішене も見つかります。これらはすべて同じ ріш ステムにまとめられます。

保存されるタイトル、要約、コンテンツ、タグはそのままの形を保つため、フィンガープリント、重複排除、順位付け、エクスポートはすべて決定論的なままです。派生した stems_text 列が追加されるのは FTS5 インデックスのみです。

次のようにして無効にできます。

$env:MEMORY_KERNEL_DISABLE_STEMMER=1

無効化されるのはクエリ側の処理のみです。書き込み時には stems_text の更新が続くため、環境変数を再び有効にしても再構築は不要です。

軽量さを保てる理由

Memory Kernel は意図的に小さく保たれています。

• 必須のベクトルデータベースではなく、SQLite + FTS5 を使用
• 常時あいまい検索を行うのではなく、決定的なランキングを使用
• メモリを際限なく増やすのではなく、重複を考慮した更新を実施
• 大量のプロンプトを渡すのではなく、コンテキストの予算を厳密に設定
• 実際に役立つ箇所に限り、オプションの Rust による高速化を利用

Python に組み込んで使用する場合、MemoryStore はスループット向上のため、長期間使用する SQLite 接続を保持します。with MemoryStore(...) as store: を使用するか、使い終わったら store.close() を呼び出してください。

対象ユーザー

次のような場合に適しています。

• 自分のマシン上でローカル優先のメモリを使いたい
• 内容を確認できる明確な記録が欲しい
• 小規模で予測可能な検索が欲しい
• 簡単にエクスポートや復元をしたい

次のような場合には、あまり適していません。

• ホスティング型のフルマネージドプラットフォームが欲しい
• ローカルでのセットアップを一切したくない
• 確認なしで、整理されていないメモを完全に自動で整理したい

プロジェクトの状況

現在の段階：動作するアルファ版です。

すでに動作しているもの：

• パッケージ構成
• CLI
• テスト
• エクスポートとインポート
• オプションの Rust アクセラレーター
• Rust を使わない Python フォールバック

現在も開発中のもの：

• 主要なプラットフォーム向けのビルド済みホイール
• よりシンプルなガイド付き取り込みフロー
• 技術者以外のユーザー向けに、さらに簡単な導入方法

ネイティブアクセラレーター

Python の実装が安定したデフォルトです。

取り込みやヒューリスティック処理のホットパスにかかるオーバーヘッドを減らしたい場合は、オプションの Rust モジュールをビルドしてください。

.\scripts\build_native.ps1

その後、memory-kernel stats で accelerator: rust が有効かどうかを確認できます。

現在のホットパスのベンチマークを実行するには、次のコマンドを使います。

python .\scripts\benchmark_ingest.py
python .\scripts\benchmark_upsert.py

プロファイリング用に、実験的なネイティブランキングを利用できます。

$env:MEMORY_KERNEL_EXPERIMENTAL_NATIVE_RANK=1

ライセンス

Apache License 2.0（LICENSE と NOTICE を参照）。0.3.1 までのバージョンは Unlicense の下でリリースされており、引き続きその条件で利用できます。それ以降のすべてのバージョンは Apache-2.0 です。貢献には DCO への署名が必要です。CONTRIBUTING.md を参照してください。

フィードバック

課題トラッカー： https://github.com/Artem362/memory-kernel/issues

課題テンプレートの選択ページ： https://github.com/Artem362/memory-kernel/issues/new/choose

初回実行時のフィードバックテンプレートもあります： .github/ISSUE_TEMPLATE/first-run-feedback.yml

初期段階で役立つ報告には、次の情報が含まれています。

• インストール元
• OS と Python のバージョン
• 実行したコマンドの正確な内容
• 期待していた動作
• 実際に起きたこと