Marginalia最新版

在向量数据库主导的个人知识库浪潮中，Marginalia 选择了一条回归本质的道路。它摒弃了常见的嵌入（Embedding）与文本切块（Chunking），转而采用图书馆学风格的结构化管理。通过 AI 驱动的“图书馆员”与“调查员”双 Agent 协作，Marginalia 能够直接阅读原始文件，提供带精确引用的回答，并随着你的使用不断进化。

核心理念：拒绝黑盒，回归结构

• 🚫 无向量库、无嵌入、无切块：避免语义搜索中的噪声与上下文丢失。
• 📚 结构化检索：依靠分类树、Tags、Views 及 Metadata 搜索，结合 Agent 对原文的直接阅读，确保答案的准确性与可追溯性。
• 📂 文件即真理：底层文件以真实文件夹形式存储在 ~/Marginalia/library/，支持 Finder 浏览、Git 版本控制及 rsync 备份。AI 仅负责索引与增强，不锁定数据。

架构揭秘：双 Agent 协作与反馈回路

Marginalia 将 AI 角色严格分离为三种身份，形成闭环：

1. 🏛️ 图书馆员 (Librarian) —— 离线批处理

• 职责：入册新文件、归并同义 Tag、重整 Catalog、维护内部状态。
• 工作模式：后台静默运行，确保知识库结构的整洁与一致性。

2. 🔍 调查员 (Investigator) —— 在线 Agent

• 职责：响应用户提问，执行 Plan → 工具调用 → 生成带引用的答案。
• 记忆机制：每轮对话结束后，将观察到的 Entry 关联写入 Journal（笔记本）。
• 工作流：
  1. Search Journal：查找相关历史线索。
  2. Read Files：直接读取原始文件内容。
  3. Synthesize：综合信息，生成答案并标注来源（如 [^a]: entry_id=...）。

3. 👤 你 (User) —— 掌控者

• 职责：上传、整理文件夹、归档、删除。
• 主权：库是你的，AI 的工作产物独立存放，互不干扰。

🔄 进化机制：Journal 反馈回路

调查员的 Journal 记录了用户的查询路径与关注点。图书馆员在后续重整时会读取 Journal，从而优化 Catalog 与 Tag 体系。这个反馈回路使得 Marginalia 越用越懂你。

关键技术特性

1. 🆔 内容寻址与多重解读

• SHA256 去重：文件按内容哈希存储，避免冗余。
• 上下文独立元数据：同一份 PDF 在 /工作 和 /研究 文件夹下可以拥有完全不同的 AI 生成的 Catalog、Extra 信息与 Tags，实现多维度的知识组织。

2. 🕸️ 发现引擎 (Discovery Engine)

为减少 Agent 循环次数，Marginalia 构建了基于关系的推荐图：

• Miner 挖掘：
  • mine_session_cooccurrence：同一对话中提及的 Entry。
  • mine_tag_overlap：共享高相似度 Tag 的 Entry。
  • mine_citation_graph：同一答案中被同时引用的 Entry。
• LLM 验证：通过 LLM 关卡 (vet_relations) 清洗噪声，建立干净的 entry_relations 图。
• Random Walk：查询时通过随机游走算法预填相关 Entry，加速检索。

3. 📄 强大的 ingestion 管道

支持多种格式的自动解析与 OCR：

• 文本/PDF：含扫描件的 VLM OCR。
• 办公文档：DOCX, Spreadsheet。
• 日志/代码：Log, Code。
• 压缩包：支持 ZIP, TAR, 7Z, RAR 等 50+ 种格式。
• 图片：VLM 缩放与描述。

快速开始

1. CLI 模式 (推荐开发者)

# 安装
pip install -e ".[dev]"

# 初始化
mkdir my-library && cd my-library
marginalia init
# 编辑 .env 填入 LLM API Key
alembic upgrade head

# 启动 REPL
marginalia

# 常用命令
marginalia> /upload paper.pdf /
marginalia> 比较一下 raft 和 paxos
marginalia> /tree
marginalia> /search "consensus algorithm"

2. 桌面应用 (开箱即用)

• Windows/macOS/Linux：提供内置 Python 运行时的安装包，无需系统环境配置。
• 注意：由于未签名，首次启动需在 macOS 运行 xattr -dr com.apple.quarantine /Applications/Marginalia.app 或在 Windows SmartScreen 中选择“仍要运行”。

适用场景

• 🎓 学术研究：需要精确引用来源，管理大量 PDF 与文献。
• 💻 技术开发：结合 Git 管理代码片段、文档与技术笔记。
• 📝 深度写作：依靠调查员 Agent 辅助调研，生成带出处的草稿。
• 🧠 第二大脑：构建长期演进、结构清晰且完全私有的知识体系。

Marginalia 是对当前“向量数据库万能论”的一次有力反思。它证明了通过结构化元数据、Agent 直接阅读与精心设计的反馈回路，可以构建出更精准、更可控、更透明的个人知识库。

对于那些重视数据主权、追求答案准确性且希望知识体系随时间生长的用户而言，Marginalia 提供了一个极具前瞻性的解决方案。立即体验，让你的知识库真正像图书馆一样井然有序且充满智慧。