knowledge-memory

Local-first, source-grounded memory infrastructure for AI agents.

AIに長期記憶を与えながら、出典・時点・状態・訂正履歴を失わず、 人間による承認を境界に置くローカル知識基盤。

Markdownをsource of truthとし、SQLiteは再生成可能なindexとして扱う。 検索とMCPの基本経路はGPUや外部LLM APIを必要としない。

Why

一般的な「AI memory」やRAGでは、検索された情報が次のように扱われやすい。

• いつの情報か分からない

• 何を根拠にしたか分からない

• 古い判断と新しい判断が混ざる

• AIが提案した内容が人間の確定事項へ混ざる

• 一度indexへ入った情報の削除・失効境界が曖昧

• private sourceとwork sourceが論理filterだけで混在する

knowledge-memory は検索精度だけでなく、provenance / lifecycle / bounded retrieval / human approval を設計の中心に置く。

検索品質で汎用RAGに勝つことは目的にしていない。違いは、取得した記録が 「どこから・いつ・どの状態で」来たかをAIと人が確認できることにある。

Related MCP server: cyber-brain

Core principles

• Source-grounded — active recordは1件以上のsource referenceを持ち、取り込んだrecordは取得時点を持つ

• Local-first — vaultとSQLite indexは利用者のマシンに置く。検索・原文取得・MCPは外部サービスへ接続しない

• Rebuildable index — DBを唯一の原本にしない

• Human-in-the-loop — AI生成候補はcandidateから始める

• Explicit lifecycle — candidate / active / superseded / retracted

• Bounded context — MCP responseとtask contextに明示的な上限を持たせる

• Fail closed — stale indexや不完全取得を成功として扱わない

• Boundary aware — personal/workはscopeだけでなくvault・DB・processを分けて運用する

Architecture

Notion / CSV / inbox text
          │
          ▼
   raw snapshot（vault外）
          │
          ▼
┌──────── Markdown vault ────────┐
│  candidate ──human review──► active
│  active ──► superseded / retracted
└────────────────────────────────┘
          │  km index（再生成可能）
          ▼
    SQLite FTS5 index
       │        │
       ▼        ▼
      CLI   stdio MCP ──► AI agent

candidateとactiveは同じvaultの中で status によって区別する。 Notionが原本の場合も、snapshotと派生Markdownを区別する。 SQLite indexはいつでもvaultから再生成できる。

What it does

• YAML frontmatter validation（km validate）

• SQLite FTS5 trigram search と3文字未満の短語のliteral search（km search）

• state/scope aware search、stale-index detection

• source-grounded record retrieval（km get）

• task context generation（km context）

• read-only stdio MCP server と応答上限付きのbounded mode（km-mcp）

• Notion read-only fetch/import、CSV import（km fetch-notion / km import-notion / km import-csv）

• explicit synchronization and availability state（km-sync）

• candidate review workflow（km-inbox。既定は非LLMの抽出。任意でloopbackのローカルモデル）

• backup / restore / recovery check / measurement（km-ops）

• question-set evaluation（km evaluate）

運用者向けの補助（必要な場合だけ使う）：

• profile境界の配備前検査（km-profile）

• sync・index・MCPの直列化、状態、復元後の照合（python -m knowledge_memory.runtime）

• 同期証跡の保持計画と明示的な削除（km-retention）

実験的な機能：

• character n-gram / 任意の埋め込みモデルによるhybrid検索（km-hybrid、opt-in。既定の検索は字面一致のまま）

• 評価用に取得量の上限を強制するMCP entry point（km-eval-budget）

Quick start

Python 3.11+ と、trigram tokenizerを含むSQLite FTS5（SQLite 3.34以降）が必要。 .[mcp] のインストール時だけ依存パッケージを取得する。以下はrepository同梱の架空データだけを使う。

python -m venv .venv
.venv/bin/python -m pip install -e '.[mcp]'

.venv/bin/km validate --vault examples/vault
.venv/bin/km index --vault examples/vault --db .state/demo.sqlite3
.venv/bin/km search --db .state/demo.sqlite3 --scope demo 育種
.venv/bin/km get --db .state/demo.sqlite3 --scope demo note-search-example

test:

.venv/bin/python -m unittest discover -s tests -v

CIはPython 3.11 / 3.12 / 3.13を対象とする。

MCP

stdio MCP serverを利用できる。

通常mode:

• search_memory

• get_memory

• build_context

bounded mode:

• search_memory_bounded

• get_memory_chunk

• build_context_bounded

.venv/bin/km-mcp --vault examples/vault --db .state/demo.sqlite3 --scope demo
.venv/bin/km-mcp --vault examples/vault --db .state/demo.sqlite3 --scope demo \
  --bounded --response-max-chars 12000 --response-max-bytes 24000

server process起動時にvault / DB / scopeを固定する。candidateの参照は起動時の --include-candidates でだけ許可し、モデルのtool引数では広げられない。 任意file readやshell executionはmemory toolとして公開しない。 bounded modeは旧tool名を広告せず、旧名による全文取得へfallbackしない。 MCP clientへの登録方法はclientごとに異なる。

MCPに接続できても、agentが自分から検索・原文取得を選ぶとは限らない。 SDKによる接続確認と、実際のclientで検索→get→出典付き回答が起きるかの確認は別に行う。 手順はdocs/mcp.mdの「Checking that an agent actually uses the server」と 導入と受け入れを参照。

Record model

recordは少なくとも次を区別する。

• stable ID

• source

• retrieval/edit/event/verification time

• lifecycle status

• claim kind

• scope

active は「通常検索で利用可能」という意味であり、「真実」と同義ではない。

詳細: docs/schema.md

Notion ingestion

Notionへは書き込まない。呼び出すのは読み取り用のAPI（page・block・data sourceの取得とquery）だけである。

Notion
  ↓  km fetch-notion（read-only API）
raw snapshot（vault外）
  ↓  km import-notion / km-sync
candidate Markdown（vault内）
  ↓  km index
search index（candidateは既定で検索対象外。--include-candidatesで明示利用）
  ↓
human review（activeへの変更は人の明示操作）

import処理は不完全なpaginationや矛盾したcursorを成功扱いしない。 取得できなくなった資料は、原文を残したまま利用保留にして検索から外す。 credential、snapshot、実vaultはrepository外に保存する。

What it does not guarantee

• source contentの真偽を自動検証しない

• scope はauthentication / authorizationではない

• search scoreはconfidenceではない

• 0 hitsは「情報が存在しない」ことの証明ではない

• MCP接続だけでagentが必ずmemoryを使うことを保証しない

• 取得した本文の中の命令をagentが実行しないことは、server側では保証できない。client側でdataとして扱う

• multi-user distributed databaseを目的としていない。単一利用者・小規模vaultを想定する

• private vaultそのものをGitHubへ保存する仕組みではない

Verification status

• 自動testとCIはsynthetic fixtureと公式MCP Python SDKのstdio clientで行う

• repository内の評価結果はsynthetic corpusに対するもの。実データでの検索・回答品質は示していない

• Notion取り込みの大量データ（API上限10,000件超）の分割取得は未実装

• km-inbox のローカルモデル利用、hybrid検索の埋め込みモデルは、特定モデルでの品質を保証しない

Repository data policy

このrepositoryにはsynthetic fixtureだけを含める。 private vault、imported articles、raw snapshot、credential、work data、実Notion ID、 private評価の質問・結果は含めない。

報告と貢献のルール: SECURITY.md、CONTRIBUTING.md

Documentation

Core design

• Architecture — 採用した設計判断と機能の境界

• Record schema — frontmatter、状態、出典と時点

• MCP — tool契約、bounded mode、agentの利用確認

Ingestion and operations

• Notion import settings と conversion

• Synchronization と data source sync

• Acceptance — 導入後に確認すること

• Operations — backup、restore、復旧確認、測定

• Inbox review — AI提案と人の承認

Advanced / experimental

• Profile boundaries — 個人・業務・公開用の分離

• Managed runtime と evidence retention

• Hybrid search — opt-inの検索比較と評価方法

Status

v0.1。最初の公開版である。 機能追加よりも、clean install、security/privacy、documentationの正確さを優先している。

License

Apache License 2.0