omni-recall

Omni-Recall：神经知识与长期上下文引擎

Omni-Recall 是一款面向 AI Agent 的高性能记忆管理技能。它能将对话历史和技术见解转换为高维向量嵌入，并存储在使用 HNSW 索引实现快速语义搜索的 Supabase（PostgreSQL + pgvector）知识集群中，从而实现跨会话的持久感知。

🚀 核心功能

1. 向量语义搜索（fetch 配合 query_text）： 使用向量相似度进行智能自然语言查询。即使措辞不同，也能找到语义相关的内容。结果按相似度得分（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 效果良好：“pgvector”、“数据库”
• 📊 短语查询通常得分为 0.60-0.66，单词查询为 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

加密保险库（键值存储）

# 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（分层可导航小世界）实现生产级性能
• 搜索：余弦相似度，阈值可配置（默认值：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 = 探索性）