Fresh-Tim-Lam/Memoria

Memoria — 本地知识图谱 IDE

将 Markdown 笔记转化为可导航、可搜索、可视化的知识网络——完全在你的机器上运行。

想快速浏览中文介绍？请看 README.cn.md。

Python
Platform
License
Version
!

Memoria 是一款面向个人知识库的本地优先知识图谱 IDE：支持带双向 [[]] 链接的 Markdown 笔记、高亮与丰富的行内标记、LaTeX 数学公式、Mermaid 图表、2D/3D 知识图谱，以及完全离线的检索内核。

你的所有数据都以纯文件形式存放在磁盘上——.md 正文加上 YAML 元数据。没有账号，没有云同步，没有隐私泄露。数据永远属于你。

为什么选择 Memoria？

| 传统笔记 | Memoria |
|--------------------|---------|
| 按文件夹组织的孤立文档 | 文档 + 知识点 + 一张图谱，任何片段都能引用其他任意片段 |
| 链接是单向跳转 | 片段范围双向链接：点击跳转 → 源片段在精确范围内高亮 → 支持后退/前进导航 |
| 复习意味着重读全部内容 | 知识点列表、待确认队列、带批量操作的完整性检查 |
| 数据锁在云端 | 本地优先、文件优先：.md + .memoria.yaml，易于备份 / 迁移 / 版本控制 |
| 功能需要联网 | 离线分词搜索 + 可选的语义检索 |

功能特性

知识图谱与双向链接

- Wiki 风格链接：[[知识点名称]] 将任意片段编织成网络。点击即可跳转到目标源片段并高亮显示，支持后退/前进导航。
- 2D / 3D 图谱：在侧边栏中切换力导向 2D 视图与空间 3D 视图；点击节点即可跳回其源位置；通过“构建”按钮重建图谱分组。
- 片段范围导航：链接解析到文档中的精确行范围——而不仅仅是整个页面。
- 多目标链接与语义边：一个链接文本可以指向多个目标——点击跳转到队列首位，其余目标保留为标签栏备选项；每条边都带有类型（引用 / 扩展 / 包含）和关联强度，在图谱构建时同步，并可单独抑制或删除。

沉浸式写作

- 三种视图：源码 / 预览 / 分栏，边写边看；可开启和关闭“编辑模式”（关闭时为只读浏览）。
- 可视化编辑：像使用文字处理器一样用鼠标涂抹高亮 / 字体颜色 / 加粗 / 斜体；更改会自动写回源码。
- 格式工具栏：粗体、斜体、高亮（黄/绿/红/蓝/橙/自定义/双色/命名）、字体颜色、图片插入。
- 样式刷与取色器：选取一种样式（粗体/斜体/高亮/字体颜色），然后按住左键拖动，将其涂抹到一段文本上；右键可一次取消一种样式。取色器管理一个自定义调色板，你可以向其中添加或移除颜色。

富文本渲染（Markdown+）

- LaTeX 数学公式：通过 MathJax 支持行内 $...$ 和块级 $$...$$，支持 cases、matrix、align、mathbb、\text 等。
- Mermaid 图表：流程图、时序图和关系图均可内联渲染。
- 图片管理：本地相对路径、远程 URL，或复制到库中（.memoria/images）；支持 Lightbox 缩放、宽度/对齐控制。
- 高亮 [[\h:color|text]]、字体颜色 [[\c:color|text]]、表格、代码块和引用的混合嵌套。

知识点管理

- 在 front-matter 中声明知识点（名称、权重、标签），或从文本中提取；侧边栏面板管理当前文件的点和链接。
- 待确认：检查发现未确认/悬空的点和链接后，可逐个或一次性全部确认。
- 候选与建议：正文提及、别名和描述会作为候选出现——一键将其采纳为别名/标签/描述；“系统建议/同步搜索辅助”从正文索引中推导出建议候选。
- 完整性检查：一键扫描整个库——悬空链接、缺失的点、结构不一致。

本地离线检索

- 内置中文分词搜索（jieba），支持全库或当前文件范围，Ctrl+K 唤出。
- 可选安装语义依赖（torch + transformers）并缓存离线模型，以启用带重排融合的语义搜索——一个真正的语义本地搜索引擎（默认离线模型 sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2 等，全部从本地缓存提供，无需网络）。

双语界面（中文/英文）

- 界面语言：设置 → 显示 → 界面语言，即时切换并自动记忆；每个界面字符串都已本地化，缺失的英文条目会回退到中文。

你的数据，你的格式

- 正文是标准 Markdown 文件；元数据存放在附属的 .memoria.yaml 中。
- 知识库就是一个普通文件夹：.md + .memoria/（索引缓存、图片、清单）。把它放进 Git、NAS 或同步盘——它随处可迁移。

截图

2D 图谱视图中的工作区：侧边栏标签栏在文件树/2D/3D 之间切换；图谱面板可通过拖动加宽，并按分组浏览。其下方是知识点列表；当前文档在右侧编辑。

3D 知识图谱：滚轮缩放，鼠标左键旋转；点击节点可跳回源文档。

分屏视图：左侧为源文档，右侧为实时渲染预览。

渲染预览：表格、wiki 链接和代码块混合布局。

数学渲染：通过 MathJax 渲染 LaTeX 公式（行内和独立显示）。

显示设置与完整性检查：可调节字号 / UI 缩放；一键结构扫描。

知识库检查与可复制报告：面板汇总完整性、清单差异和图谱边问题；“复制报告”会将 Markdown 报告放入剪贴板，并在底部以提示确认。

快速上手

前置条件：开发需要 Python ≥ 3.11；桌面外壳需要 Windows 10/11 x64。该外壳基于 pywebview 构建，需要 .NET Framework 4.7.2+ 和 WebView2 运行时——两者均已包含在 Windows 10 1803+ 和 Windows 11 中。

1. 安装（开发模式，包含 pytest）
pip install -e ".[dev]"

2. 启动桌面应用
python app.py
或开发模式（DevTools + 无边框窗口）
.\scripts\run_dev.ps1

点击 Open Knowledge Base，选择任意包含 Markdown 文件的文件夹。想立即试用，可打开内置的官方展示知识库（机器学习入门；涵盖样式、图片、链接、搜索）：

docs\example\showcase\    # 官方展示：35 个知识点、跨页链接、图片、别名

想要独立 exe？运行 .\packaging\build_release.cmd；输出位于 Package\Memoria.exe。

使用打包版本（Memoria-v*-win64.zip）？请先将整个压缩包解压到可写文件夹——切勿直接从 zip 内运行 Memoria.exe。如果启动失败，exe 旁边的 crash.log 中有详细信息；如果 Windows 因文件来自 Internet 而阻止捆绑的 .NET 运行时，请在解压后的文件夹中运行 Get-ChildItem -Recurse | Unblock-File，然后重试。

语法速览

Memoria 兼容标准 Markdown，并扩展了知识链接和富标记：

我的笔记

Wiki 链接
[[Transformer]] 值得重读。

高亮 / 字体颜色
这是 [[\h:yellow|一个关键要点]]，那是 [[\c:red|一个必须修复的结论]]。
双色高亮：[[\h:green:blue|绿色背景，蓝色文字]]

数学（MathJax）
行内 $E = mc^2$，块级：

$$
\mathrm{Attention}(Q,K,V)=\mathrm{softmax}\!\left(\frac{QK^\top}}\right)V
$$

图片（本地 / 远程 / 灯箱）
diagram

Mermaidmermaid
graph LR
A[[Markov Decision Process]] --> B[[Bellman Equation]]
A --> C[[Q-Learning]]

有关渲染格式和样式，请参阅 docs/reference/preview-formats.md；有关语法规范，请参阅 docs/conventions/markdown-form-std.md。

技术栈

| 层级 | 技术 | 说明 |
|-------|-----------|-------|
| 语言 | Python ≥ 3.11 | src 布局，由 pyproject.toml 管理 |
| 桌面外壳 | pywebview（Chromium），可选 pyqt6 | 通过 MEMORIA_SHELL 环境变量切换 |
| Web 服务 | bottle | 静态资源 + /files/ 知识库文件路由（防目录遍历）+ /rpc API 桥接 |
| 前端 | 原生 JS（零框架） | parser.js 将源码编译为 AST → renderer.js 渲染 DOM；编辑内容会写回并重新编译 |
| 渲染 | marked / MathJax / mermaid / three.js | Markdown、数学公式、图表、3D 图谱 |
| 存储 | 文件系统 + YAML | sidecar .memoria.yaml + .memoria/ 元数据目录（索引 / 图片 / 清单） |
| 检索 | jieba 词法；可选 sentence-transformers / pypinyin | 语义检索和重排为可选依赖 |

前端数据流：source → parser.js (AST) → renderer.js (DOM) → preview；edit-handler.js 将可视化编辑写回源码并触发重新编译，因此源码与预览永远不会脱节。

文档与 AI 协作

Memoria 的文档专为人类 + 智能体协作而设计：每个顶层目录都带有 README.md，契约级规则位于 docs/conventions/ 下。

- 入门指南（请先阅读）：AGENT.md
- 文档中心：docs/README.md
- 架构：docs/reference/architecture.md、docs/design/system-design.md
- 设计里程碑：docs/design/designV0.md
- 版本的唯一事实来源：src/memoria/\_\_version\_\_.py（当前为 0.3.2）

项目结构

├── src/            # 源码（Python 包 + 前端静态资源）→ src/README.md
├── tests/          # 单元/集成测试（pytest）                 → tests/README.md
├── docs/           # 文档中心（conventions / guides / reference / samples）→ docs/README.md
├── scripts/        # 开发工具（运行与基准测试）                   → scripts/README.md
├── packaging/      # 发布构建（build_release.cmd → Package/）    → packaging/README.md
├── resources/      # 应用资源（图标、演示截图）        → resources/README.md
├── benchmarks/     # 检索评估数据与结果             → benchmarks/README.md
├── config/         # 应用配置（ui-settings.json）            → config/README.md
└── app.py          # 源码运行入口

路线图

- 已完成（0.x）：片段范围双向链接与跳转高亮；知识点与 sidecar YAML 元数据；2D/3D 图谱；富渲染（数学 / Mermaid / 高亮器 / 图片）；待确认列表与完整性检查；带冲突报告的批量扁平文件导入；离线检索内核。
- 计划中：检索基准测试框架；更强的语义搜索；更多桌面外壳 / 平台。

详见 docs/design/designV0.md。

许可证

MIT © 2026 FreshTim