内存系统

┌─────────────────────────────────────────┐
│              Agent Loop                  │
└─────────────────┬───────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────┐
│           Memory Subsystem               │
├─────────────────────────────────────────┤
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  │
│  │ Session │  │ Vector  │  │Knowledge│  │
│  │ Store   │  │ Search  │  │ Graph   │  │
│  └─────────┘  └─────────┘  └─────────┘  │
├─────────────────────────────────────────┤
│           SQLite Database               │
└─────────────────────────────────────────┘

[memory]
decay_rate = 0.05
sqlite_path = "~/.librefang/data/librefang.db"

[memory]
decay_rate = 0.05
sqlite_path = "~/.librefang/data/librefang.db"
vector_dimension = 1536
max_memory_items = 10000
auto_compact = true

# 创建新会话
librefang session create --name "research-project"

# 列出所有会话
librefang session list

# 查看会话详情
librefang session info <session-id>

# 删除会话
librefang session delete <session-id>

# 压缩会话
librefang session compact <session-id>

# 导出会话
librefang session export <session-id> --format json

# 存储简单键值（位置参数：agent key value）
librefang memory store <agent> "user:preference:theme" "dark"

# 示例：为 coder agent 存储版本信息
librefang memory store coder "project:version" "1.0"

# 等价形式：使用 set 子命令
librefang memory set coder "note:1" "Important note"

# 关键词搜索
librefang memory search "project"

# 向量搜索 (语义搜索)
librefang memory search --vector "find information about AI agents"

# 带过滤的搜索
librefang memory search "meeting" --tags "work" --limit 10

# 读取记忆
librefang memory get <key>

# 更新记忆
librefang memory update <key> --value "new value"

# 删除记忆
librefang memory delete <key>

# 列出所有记忆
librefang memory list --prefix "project:"

# 语义搜索示例
librefang memory search --vector "machine learning techniques for text classification"

[memory]
similarity_threshold = 0.75

# 语义搜索 API（GET 请求，使用查询参数）
curl "http://127.0.0.1:4545/api/memory/search?q=find+information+about+AI&limit=10&threshold=0.8"

# 添加实体
librefang kg add-entity --type "person" --name "John Doe" --properties '{"role": "developer"}'

# 列出实体
librefang kg list-entities --type "person"

# 搜索实体
librefang kg search-entities "John"

# 添加关系
librefang kg add-relation \
  --from "person:john" \
  --relation "works_at" \
  --to "company:acme"

# 列出关系
librefang kg list-relations --entity "person:john"

# 查询关系
librefang kg query --from "person:john" --relation "works_at"

# 查询路径
librefang kg path --from "person:alice" --to "company:acme"

# 查询子图
librefang kg subgraph --entity "person:bob" --depth 2

# 压缩会话
librefang session compact <session-id>

# 压缩所有会话
librefang session compact-all

# 查看压缩状态
librefang session compaction-status

# ~/.librefang/config.toml
[auto_dream]
enabled = true
min_hours = 24         # 同一 agent 再次梦境的最短间隔
min_sessions = 5       # 上次梦境之后至少触及这么多会话才会触发

# agent manifest (.toml)
auto_dream_enabled = true

# 可选：用 per-agent 覆盖全局阈值
auto_dream_min_hours = 168      # 每周一次，适合低频 agent
auto_dream_min_sessions = 1     # 每个会话之后都触发，适合高频 agent

#[async_trait]
pub trait MemoryProvider: Send + Sync {
    /// A short, unique name for this provider (e.g. "pinecone", "weaviate").
    fn name(&self) -> &str;

    /// Returns `true` for the built-in provider, `false` for all external providers.
    fn is_builtin(&self) -> bool;

    /// Returns a text block to inject into the agent system prompt at session start,
    /// or `None` if there is nothing to inject for this session.
    async fn system_prompt_block(&self, session_id: &str) -> Option<String>;

    /// Fetches relevant context for the given query string before an LLM call.
    /// The returned string is appended to the context window.
    async fn prefetch(&self, query: &str, session_id: &str) -> Result<String, MemoryError>;

    /// Called after each agent turn completes. Use this hook to index new content,
    /// synchronize state, or flush write buffers to the external backend.
    async fn on_turn_complete(&self, session_id: &str, turn_summary: &str) -> Result<(), MemoryError>;
}

use librefang_memory::{MemoryManager, MemoryProvider};

// Build your custom provider
let my_provider: Arc<dyn MemoryProvider> = Arc::new(MyVectorDbProvider::new(config));

// Register it with the memory manager
memory_manager.set_external_provider(my_provider).await;

// Called internally by the agent loop before each LLM request
let context = memory_manager.prefetch_all(&user_query, &session_id).await;

# 查看使用统计
librefang usage

# 查看 Agent 使用
librefang usage --agent <agent-id>

# 查看提供商使用
librefang usage --provider

# 查看成本
librefang cost

# 按时间范围查看成本
librefang cost --from 2025-01-01 --to 2025-01-31

# 导出报告
librefang cost export --format csv

decayed_conf = original_conf × e^(-decay_rate × days_since_access)
final_conf   = min(decayed_conf × (1 + log2(access_count)), 1.0)

# 重建向量索引
librefang memory reindex

# 检查索引状态
librefang memory index-status

# 清理旧数据
librefang memory cleanup --older-than 30d

# 压缩数据库
librefang memory vacuum

# 检查数据库完整性
librefang doctor

# 恢复备份
librefang memory restore --backup <path>