Basic Memory核心架构揭秘：本地Markdown如何变成语义知识图谱-平芜编程栈

Basic Memory核心架构揭秘：本地Markdown如何变成语义知识图谱

【免费下载链接】basic-memoryAI conversations that actually remember. Never re-explain your project to your AI again. Join our Discord: https://discord.gg/tyvKNccgqN项目地址: https://gitcode.com/gh_mirrors/ba/basic-memory

Basic Memory是一款本地优先的知识管理系统，它能将普通的Markdown文件转化为结构化的语义知识图谱，让AI真正记住你的项目信息，无需反复解释。本文将深入剖析其核心架构，展示Markdown文本如何通过一系列处理转化为智能知识网络。

知识类型的智能分类：从原始内容到结构化数据

Basic Memory采用独特的知识类型分类体系，将各类信息有序组织。系统将知识分为四大类，每类都有其独特的处理方式和应用场景。

笔记（Notes）：包含原始内容、简单格式和快速捕获的信息，是知识的基础来源
文档（Documents）：富文本、结构化内容和格式化数据，提供更正式的知识表达
媒体（Media）：处理图片、视频和音频等非文本信息，丰富知识的表现形式
数据（Data）：结构化、可查询且相互关联的信息，是构建知识图谱的核心

核心架构概览：三大入口与依赖注入模式

Basic Memory采用模块化设计，主要通过三个入口点提供服务：API（FastAPI REST服务器）、MCP（模型上下文协议服务器）和CLI（命令行界面）。每个入口点都使用组合根（Composition Root）模式来管理配置和依赖关系。

组合根模式：依赖注入的精髓

组合根是应用中唯一连接依赖的地方，在Basic Memory中，每个入口点都有自己的组合根，负责：

从ConfigManager读取配置
解析运行时模式（本地/测试）
创建并向下游代码提供依赖

这种设计确保只有组合根读取全局配置，其他模块都通过显式方式接收配置，大大提高了代码的可维护性和可测试性。

src/basic_memory/ ├── api/ │ └── container.py # ApiContainer ├── mcp/ │ └── container.py # McpContainer ├── cli/ │ └── container.py # CliContainer └── runtime.py # RuntimeMode enum and resolver

Markdown到知识图谱的转化流程：从文本到智能连接

Basic Memory将Markdown转化为知识图谱的过程分为几个关键步骤，每个步骤都由专门的模块处理，形成一个完整的流水线。

1. Markdown解析与实体提取

在src/basic_memory/markdown/目录中，entity_parser.py和markdown_processor.py负责解析Markdown内容，提取实体、关系和元数据。系统能够识别标题、列表、链接等Markdown元素，并将其转换为结构化数据。

解析过程不仅提取显式信息，还通过schema/inference.py进行模式推断，自动识别实体类型和关系，即使Markdown中没有明确标注。

2. 语义索引构建：从文本到向量

语义索引是Basic Memory的核心功能之一，由src/basic_memory/indexing/和src/basic_memory/repository/中的模块共同实现。系统将文本内容分割为语义块，每个块都生成向量嵌入：

分块策略：标题开始新块，每个项目符号成为独立块， prose部分合并为约900字符的块
去重机制：使用source_hash（块文本的SHA-256）避免重复嵌入
嵌入 providers：支持本地的FastEmbed和云端的OpenAI，满足不同场景需求

# 构建向量嵌入的命令 bm reindex --embeddings

3. 知识图谱存储与查询

处理后的语义数据存储在关系型数据库中，同时利用向量数据库提供高效的语义搜索。系统支持SQLite（本地）和Postgres（云端）两种后端：

SQLite：使用sqlite-vec扩展存储向量，适合本地使用
Postgres：结合pgvector和HNSW索引，提供高性能的云端向量搜索

通过src/basic_memory/repository/search_repository.py，系统实现了文本搜索、向量搜索和混合搜索三种模式，满足不同的查询需求。

同步协调：保持知识图谱与文件系统一致

SyncCoordinator（位于src/basic_memory/sync/coordinator.py）负责管理文件同步和监视生命周期，确保知识图谱与文件系统的内容保持一致。它维护同步状态，并协调同步任务和监视服务的启动与停止。

同步过程采用增量更新策略，只处理修改过的内容，大大提高了效率。对于语义嵌入，系统会检查内容哈希，只对变化的内容重新生成向量。

项目解析：多项目管理的核心

ProjectResolver（位于src/basic_memory/project_resolver.py）提供统一的项目选择机制，支持多项目管理。它通过三级层次结构解析项目：显式项目参数、配置中的默认项目和唯一可用项目，确保在各种场景下都能正确选择目标项目。

结语：本地优先的智能知识管理

Basic Memory通过精巧的架构设计，将简单的Markdown文件转化为强大的语义知识图谱。其本地优先的设计确保数据安全和隐私，同时提供与云端服务的无缝集成选项。无论是个人知识管理还是团队协作，Basic Memory都能帮助用户构建一个真正智能的知识系统，让AI助手能够持续学习和理解你的项目信息。

要开始使用Basic Memory，只需克隆仓库并按照安装指南操作：

git clone https://gitcode.com/gh_mirrors/ba/basic-memory cd basic-memory pip install .

探索docs/ARCHITECTURE.md了解更多技术细节，或通过bm --help查看命令行工具的使用方法。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Basic Memory核心架构揭秘：本地Markdown如何变成语义知识图谱