omni-recall

Omni-Recall：ニューラルナレッジ＆長期コンテキストエンジン

Omni-Recallは、AI エージェント向けに設計された高性能なメモリ管理スキルです。会話履歴や技術的な知見を高次元のベクトル埋め込みに変換し、HNSWインデックスによる高速なセマンティック検索に対応したSupabase（PostgreSQL + pgvector）のナレッジクラスターに保存することで、セッションをまたいだ永続的な認識を可能にします。

🚀 主な機能

1. ベクトルセマンティック検索（query_textを使ったfetch）： ベクトル類似度を使って、自然言語で柔軟に検索できます。表現が異なっていても、意味的に関連するコンテンツを見つけます。結果は類似度スコア（0～1）順に返されます。デフォルトのしきい値は0.5です（再現率と適合率のバランスを重視）。

2. ニューラル同期（sync）： 設定済みのLLMHub埋め込みモデルを使って、現在のセッション状態、ユーザー設定、操作手順をベクトル化します。デフォルトはOpenAIのtext-embedding-3-smallです。重複の自動検出に対応しており（コサイン類似度が0.9を超える場合はスキップします）、任意のcategoryフィールドとimportanceフィールドもサポートします。

3. コンテキスト取得（fetch）： 自然言語のクエリまたは時間ベースのフィルターを使って、過去のニューラルレコードを取得します。類似度のしきい値（0.5～0.9）の調整と、カテゴリによるフィルタリングに対応しています。

4. ユーザープロファイル管理（sync-profile / fetch-profile）： ベクトル検索に対応した専用のprofilesマトリックスで、ユーザーの役割、設定、環境設定、ペルソナを管理します。

5. AI 指示管理（sync-instruction / fetch-instruction）： セマンティック検索機能を備えた、AI向けの操作要件を保存します。

---

🛠 使用例

ベクトルセマンティック検索（推奨）

# Search with natural language (default threshold: 0.5)
python scripts/omni_ops.py fetch "如何优化数据库性能" none 10

# Search with custom similarity threshold
python scripts/omni_ops.py fetch "pgvector 索引优化" none 10 none 0.7

# Search last 7 days for AI-related content
python scripts/omni_ops.py fetch "AI Agent 开发" 7 10

# Search instructions with semantic understanding
python scripts/omni_ops.py fetch-instruction "代码风格规范" none 0.5 5

# Search profiles
python scripts/omni_ops.py fetch-profile "用户技能背景" none 0.5 5

# List all records (use 'none' as query)
python scripts/omni_ops.py fetch none 30 10

類似度しきい値ガイド

しきい値	説明	使用例
0.5	バランス型（デフォルト） ⭐	一般的な検索。より多くの結果を返します
0.6-0.65	より高い適合率	より具体的な一致
0.7-0.8	高い適合率	完全一致や、非常に具体的なクエリ
0.8+	非常に高精度	ほぼ完全一致するもののみ

クエリのベストプラクティス：

• ✅ フレーズで検索します（3～5語）。例：「pgvector インデックス最適化」、「データベースパフォーマンス最適化」
• ✅ デフォルトの0.5では、単語1つでの検索も有効です。例：「pgvector」、「データベース」
• 📊 フレーズ検索のスコアは通常0.60～0.66、単語1つの検索では0.53～0.57です
• 🎯 デフォルトの0.5はバランスが良く、関連する結果を3～10件返します

セッションコンテキストの同期

# Basic sync
python scripts/omni_ops.py sync "User is interested in Python optimization." "session-tag" 0.9

# Sync with category and importance
python scripts/omni_ops.py sync "New tech stack insight" "research" 0.9 "technical" 0.8

ユーザープロファイルの同期

# Set a persona
python scripts/omni_ops.py sync-profile "persona" "Experienced Senior Backend Engineer, favors Go and Python."

# Set a preference
python scripts/omni_ops.py sync-profile "preference" "Prefers concise code without excessive comments."

AI 指示の同期

# Set tone
python scripts/omni_ops.py sync-instruction "tone" "Professional yet friendly, use 'Partner' as my nickname."

# Set workflow steps
python scripts/omni_ops.py sync-instruction "workflow" "1. Plan -> 2. Implementation -> 3. Verification -> 4. Summary."

暗号化されたNsfwメモリ（センシティブなコンテキスト）

# Sync sensitive content (Encrypted at rest + Vector embedding)
python scripts/omni_ops.py sync-nsfw "Sensitive information here" "private-tag" 0.9

# Fetch with semantic search
python scripts/omni_ops.py fetch-nsfw "敏感查询" 30 10 none 0.5

# Fetch full context including nsfw records
python scripts/omni_ops.py fetch-full-context 10 none true

暗号化されたVault（キーと値のストレージ）

# Store an encrypted value
python scripts/omni_ops.py sync-vault "ZHIHU_COOKIE" "your_long_cookie_string"

# Fetch and decrypt a value
python scripts/omni_ops.py fetch-vault "ZHIHU_COOKIE"

ドキュメント／URLの一括同期

# Sync a markdown file (H1-H5 Splitting)
python scripts/omni_ops.py batch-sync-doc "/path/to/doc.md" "tag" 0.9

# Sync a web page via URL
python scripts/omni_ops.py batch-sync-doc "https://example.com/article" "web-source" 0.9

コンテキスト全体の取得（初回の想起に推奨）

優先順位：1. instructions（ペルソナ／ルール）> 2. profiles（ユーザー情報／設定）> 3. memories（セッション履歴）。

# Get ALL instructions + ALL profiles + memories from last 10 days
python scripts/omni_ops.py fetch-full-context 10

---

🏗 スキーマのセットアップ（Supabase / Postgres）

1. Supabaseナレッジクラスター

ニューラルストレージ層を初期化するには、Supabaseプロジェクトで次のSQLを実行します。

-- Enable the pgvector extension for high-dimensional search
create extension if not exists vector;

-- Create the neural memory matrix with halfvec for efficiency
create table if not exists public.memories (
  id bigint primary key generated always as identity,
  content text not null,          -- Raw neural content
  embedding vector(1536),        -- Neural vector (text-embedding-3-small)
  metadata jsonb,                -- Engine & session metadata
  source text,                   -- Uplink source identifier
  category text default 'general',-- Memory category
  importance real default 0.5,   -- Memory importance weight (0.0-1.0)
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- HNSW index for fast approximate nearest neighbor search (recommended for production)
create index on public.memories using hnsw (embedding vector_cosine_ops) 
  with (m = 16, ef_construction = 64);

-- Create the user profiles matrix
create table if not exists public.profiles (
  id uuid primary key default gen_random_uuid(),
  category text not null,        -- 'role', 'preference', 'setting', 'persona'
  content text not null,         -- Profile description
  embedding vector(1536),       -- Neural vector
  metadata jsonb,               -- Versioning & source
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- HNSW index for profiles
create index on public.profiles using hnsw (embedding vector_cosine_ops)
  with (m = 16, ef_construction = 64);

-- Create the AI instructions matrix
create table if not exists public.instructions (
  id uuid primary key default gen_random_uuid(),
  category text not null,        -- 'tone', 'workflow', 'rule', 'naming'
  content text not null,         -- Instruction detail
  embedding vector(1536),       -- Neural vector
  metadata jsonb,               -- Versioning & source
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- HNSW index for instructions
create index on public.instructions using hnsw (embedding vector_cosine_ops)
  with (m = 16, ef_construction = 64);

-- Create the nsfw matrix (Encrypted Sensitive Memories)
create table if not exists public.nsfw_memories (
  id bigint primary key generated always as identity,
  content text not null,          -- Encrypted neural content (AES-256)
  embedding vector(1536),        -- Neural vector (unencrypted for search)
  source text,                   -- Uplink source identifier
  category text default 'general',-- Memory category
  importance real default 0.5,   -- Memory importance weight (0.0-1.0)
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- HNSW index for nsfw_memories
create index on public.nsfw_memories using hnsw (embedding vector_cosine_ops)
  with (m = 16, ef_construction = 64);

-- Create the encrypted vault table
create table if not exists public.vault (
  key text primary key,          -- Unique variable name
  value text not null,           -- Encrypted content (AES-256)
  updated_at timestamptz default now()
);

2. 環境設定

ニューラルアップリンクに必要な変数：

• LLMHUB_TOKEN：ニューラルエンコーディングAPIの認証情報（llmhub.ltd）
• LLMHUB_EMBEDDING_MODEL：任意の埋め込みモデル名。デフォルトはtext-embedding-3-smallです
• SUPABASE_PASSWORD：PostgreSQLナレッジベースの認証情報

🧠 エンジニアリング原則

• 次元数：1536次元のベクトル空間（text-embedding-3-small）
• インデックス作成：本番環境向けのパフォーマンスを実現するHNSW（Hierarchical Navigable Small World）
• 検索：設定可能なしきい値を使ったコサイン類似度（デフォルト：0.5）
• プロトコル：HTTPS / WebSockets（Psycopg2経由）
• レイテンシ：リアルタイムのサブ秒同期に最適化
• コンテキストの優先順位：instructions > profiles > memories

📚 ドキュメント

• クイックスタート：QUICK_START.md - 5 分で使い始められます
• CLI の使い方：CLI_USAGE_EXAMPLES.md - 包括的な使用例
• API リファレンス：VECTOR_SEARCH_API.md - API の完全なドキュメント
• しきい値ガイド：DEFAULT_THRESHOLD_RECOMMENDATION.md - 調整ガイド

⚠️ 注意事項

• ホスト環境に psycopg2 と requests があることを確認してください
• 過去の目標との整合性を保つため、ミッションの開始時には必ず fetch-full-context を実行してください
• マイルストーンの完了時には、ニューラル永続性を確保するために sync を実行してください
• インテリジェントなセマンティック検索には、ベクトル検索（query_text）を使用してください
• ニーズに応じて類似度のしきい値を調整してください（0.6 = バランス型、0.7 = 精密型、0.5 = 探索型）