🌳 MindTree

轻量级终端 AI 个人知识记忆树与智能检索引擎
Lightweight Terminal AI Personal Knowledge Memory Tree & Intelligent Search Engine

pip install mindtree
_{一键安装，即刻开始构建你的知识树 🚀}

---

简体中文  |  繁體中文  |  English

---

🎉 简体中文

📖 项目介绍

MindTree 是一款专为终端用户打造的轻量级个人知识管理工具。它以树形层级结构组织你的知识节点，内置 TF-IDF 全文搜索引擎，支持中英文智能分词，并提供精美的 TUI 终端仪表板用于可视化展示。

无论你是开发者、研究者还是终身学习者，MindTree 都能帮你在终端中高效地记录、组织、检索你的知识碎片，构建属于你自己的第二大脑。

为什么选择 MindTree？

• 🌲 树形思维 -- 用层级结构模拟大脑的知识网络，而非扁平的笔记列表
• 🔍 智能搜索 -- TF-IDF 算法 + 中英文 bigram 分词，精准定位你的知识
• 🎨 终端美学 -- 彩色树形展示、搜索结果可视化、统计面板，终端也能很好看
• 🪶 零依赖 -- 纯 Python 标准库实现，pip install 即装即用，无需任何额外依赖
• 📦 轻量便携 -- 所有数据存储在本地 JSON 文件中，方便备份和迁移

---

✨ 核心特性

特性	说明
🌳 层级知识树管理	创建、编辑、删除知识节点，支持无限层级的父子关系
📝 5 种节点类型	note(笔记)、concept(概念)、reference(参考)、task(任务)、idea(想法)
🔍 TF-IDF 全文搜索	支持中英文分词、bigram 增强、标签过滤、类型过滤
🔗 节点关联链接	在节点间创建语义关联，构建知识图谱雏形
🎨 TUI 终端仪表板	彩色树形展示、搜索结果可视化、统计面板、重要性星标
📤 Markdown/JSON 导入导出	灵活的数据交换格式，方便与其他工具集成
⭐ 重要性评分系统	0-10 星评分，帮你快速识别核心知识
🪶 零外部依赖	纯 Python 标准库实现，兼容 Python 3.8+

---

🚀 快速开始

安装

# 从 PyPI 安装（推荐）
pip install mindtree

# 本地开发安装
git clone https://github.com/gitstq/MindTree.git
cd MindTree
pip install -e .

五分钟上手

# 1️⃣ 初始化知识树
mindtree init

# 2️⃣ 添加你的第一个知识节点
mindtree add "Python 学习路线" --type concept --tags "python,学习" --content "从基础语法到高级特性" --importance 8

# 3️⃣ 添加子节点，构建知识层级
mindtree add "基础语法" --parent <父节点ID> --type note --tags "python,基础" --content "变量、数据类型、控制流"

# 4️⃣ 搜索知识
mindtree search "python 基础" --type note

# 5️⃣ 查看知识树全貌
mindtree tree --depth 3

# 6️⃣ 查看统计面板
mindtree stats

---

📖 详细使用指南

🌳 知识树管理

mindtree init -- 初始化知识树

在当前用户目录下创建 ~/.mindtree/ 数据目录，用于存储知识树数据。

mindtree init

mindtree add -- 添加知识节点

创建一个新的知识节点，支持指定类型、标签、父节点和内容。

# 基本用法
mindtree add "标题"

# 完整参数
mindtree add "机器学习入门" \
  --type concept \
  --tags "ml,ai,学习" \
  --content "机器学习是人工智能的一个子领域..." \
  --importance 7 \
  --parent <父节点ID>

参数说明：

参数	说明	默认值
title	节点标题（必填）	-
--type	节点类型：note / concept / reference / task / idea	note
--tags	逗号分隔的标签列表	空
--parent	父节点 ID	无（作为根节点）
--content	节点内容	空
--importance	重要性评分（0-10）	5

mindtree show <ID> -- 查看节点详情

展示指定节点的完整信息，包括类型、标签、重要性、内容、关联链接等。

mindtree show <节点ID>

mindtree edit <ID> -- 编辑节点

修改已有节点的标题、内容、标签、类型或重要性评分。

# 修改标题和内容
mindtree edit <节点ID> --title "新标题" --content "新内容"

# 修改标签和重要性
mindtree edit <节点ID> --tags "新标签1,新标签2" --importance 9

# 修改节点类型
mindtree edit <节点ID> --type concept

mindtree delete <ID> -- 删除节点

删除指定节点。如果节点有子节点，需要使用 --recursive 参数递归删除。

# 删除叶子节点
mindtree delete <节点ID>

# 递归删除节点及其所有子节点
mindtree delete <节点ID> --recursive

mindtree link <ID1> <ID2> -- 创建节点关联

在两个节点之间建立语义关联关系。

# 创建关联
mindtree link <节点ID1> <节点ID2> --relation "相关"

# 其他关联类型示例
mindtree link <ID1> <ID2> --relation "依赖"
mindtree link <ID1> <ID2> --relation "扩展"
mindtree link <ID1> <ID2> --relation "对比"

mindtree tree -- 展示知识树

以彩色树形结构展示知识树，支持指定展示深度。

# 默认展示 3 层
mindtree tree

# 指定展示深度
mindtree tree --depth 5

mindtree path <ID> -- 查看节点路径

展示从根节点到指定节点的完整路径。

mindtree path <节点ID>
# 输出示例：根节点 > 子节点 > 目标节点

---

🔍 搜索与查询

mindtree search -- 全文搜索

使用 TF-IDF 算法对知识树进行全文搜索，支持中英文分词和多种过滤条件。

# 基本搜索
mindtree search "机器学习"

# 按类型过滤
mindtree search "python" --type concept

# 按标签过滤
mindtree search "算法" --tags "python,数据结构"

# 限制结果数量
mindtree search "设计模式" --limit 10

# 组合使用
mindtree search "并发编程" --type note --tags "python,多线程" --limit 5

参数说明：

参数	说明	默认值
query	搜索关键词（必填）	-
--type	按节点类型过滤	不过滤
--tags	按标签过滤（逗号分隔）	不过滤
--limit	最大返回结果数	20

mindtree tags -- 查看所有标签

列出知识树中所有标签及其使用次数，按频率排序。

mindtree tags

mindtree recent -- 查看最近更新

展示最近更新的知识节点列表。

# 默认显示最近 10 条
mindtree recent

# 指定显示数量
mindtree recent --limit 20

---

📤 导入导出

mindtree export -- 导出知识树

将知识树导出为 Markdown 或 JSON 格式。

# 导出为 Markdown
mindtree export --format md --output knowledge.md

# 导出为 JSON
mindtree export --format json --output knowledge.json

# 导出指定子树
mindtree export --node <节点ID> --format md --output subtree.md

mindtree import -- 导入知识树

从 JSON 文件导入知识树数据。

mindtree import knowledge.json

---

📊 系统命令

mindtree stats -- 统计面板

展示知识树的统计信息，包括节点数量、类型分布、热门标签、访问频率等。

mindtree stats

全局选项

# 指定自定义数据目录
mindtree --data-dir /path/to/custom/dir tree

# 禁用彩色输出
mindtree --no-color search "关键词"

# 查看版本信息
mindtree --version

---

💡 设计思路与迭代规划

设计理念

MindTree 的核心设计理念是**「让知识管理回归终端」**。在工具日益繁杂的今天，我们相信终端依然是最简洁、最高效的知识管理环境：

1. 层级 > 扁平 -- 人类思维天然是层级的，树形结构比扁平列表更贴近认知模型
2. 搜索 > 分类 -- 好的搜索引擎让你不再纠结「该放在哪个文件夹」
3. 简单 > 复杂 -- 零依赖、纯标准库，安装即用，不被工具绑架
4. 本地 > 云端 -- 数据存储在本地，隐私安全，离线可用

架构设计

MindTree
├── engine.py    # 核心引擎：节点管理、索引、搜索、持久化
├── cli.py       # 命令行接口：参数解析、命令分发
└── tui.py       # 终端界面：树形渲染、搜索结果、统计面板

未来规划

• 🔌 插件系统 -- 支持自定义节点类型和搜索后端
• 🌐 Web UI -- 提供可选的 Web 界面用于可视化浏览
• 📱 同步功能 -- 支持多设备间的知识树同步
• 🤖 AI 增强 -- 集成本地 LLM 实现智能摘要和问答
• 📊 知识图谱 -- 基于节点关联生成可视化知识图谱
• 🔔 复习提醒 -- 基于艾宾浩斯遗忘曲线的间隔复习

---

📦 打包与部署指南

本地开发

# 克隆仓库
git clone https://github.com/gitstq/MindTree.git
cd MindTree

# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest

# 运行测试（含覆盖率）
pytest --cov=mindtree

构建发布包

# 安装构建工具
pip install build

# 构建 sdist 和 wheel
python -m build

# 生成的包在 dist/ 目录下
ls dist/
# mindtree-1.0.0.tar.gz
# mindtree-1.0.0-py3-none-any.whl

发布到 PyPI

# 安装 Twine
pip install twine

# 检查包
twine check dist/*

# 上传到 PyPI
twine upload dist/*

系统要求

• Python >= 3.8
• 操作系统：Linux、macOS、Windows 均可
• 外部依赖：无（零依赖设计）

---

🤝 贡献指南

我们欢迎并感谢所有形式的贡献！无论是提交 Bug、改进文档，还是贡献代码。

贡献流程

1. 🍴 Fork 本仓库
2. 🌿 创建特性分支：git checkout -b feature/amazing-feature
3. 💾 提交更改：git commit -m 'Add some amazing feature'
4. 📤 推送到分支：git push origin feature/amazing-feature
5. 🎉 提交 Pull Request

代码规范

• 遵循 PEP 8 编码规范
• 编写单元测试覆盖新功能
• 保持零外部依赖的设计原则
• 添加清晰的文档字符串和注释

报告问题

如果遇到 Bug 或有功能建议，请在 GitHub Issues 中提交。

---

📄 开源协议

本项目基于 MIT License 开源。

MIT License

Copyright (c) 2024 gitstq

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

---

🎉 繁體中文

📖 專案介紹

MindTree 是一款專為終端使用者打造的輕量級個人知識管理工具。它以樹狀層級結構組織你的知識節點，內建 TF-IDF 全文搜尋引擎，支援中英文智慧分詞，並提供精美的 TUI 終端儀表板用於視覺化呈現。

無論你是開發者、研究員還是終身學習者，MindTree 都能幫你在終端中高效地記錄、組織、檢索你的知識碎片，建構屬於你自己的第二大脑。

為什麼選擇 MindTree？

• 🌲 樹狀思維 -- 用層級結構模擬大腦的知識網路，而非扁平的筆記列表
• 🔍 智慧搜尋 -- TF-IDF 演算法 + 中英文 bigram 分詞，精準定位你的知識
• 🎨 終端美學 -- 彩色樹狀展示、搜尋結果視覺化、統計面板，終端也能很好看
• 🪶 零依賴 -- 純 Python 標準函式庫實作，pip install 即裝即用，無需任何額外依賴
• 📦 輕量便攜 -- 所有資料儲存在本地 JSON 檔案中，方便備份與遷移

---

✨ 核心特性

特性	說明
🌳 層級知識樹管理	建立、編輯、刪除知識節點，支援無限層級的父子關係
📝 5 種節點類型	note(筆記)、concept(概念)、reference(參考)、task(任務)、idea(想法)
🔍 TF-IDF 全文搜尋	支援中英文分詞、bigram 增強、標籤過濾、類型過濾
🔗 節點關聯連結	在節點間建立語意關聯，建構知識圖譜雛形
🎨 TUI 終端儀表板	彩色樹狀展示、搜尋結果視覺化、統計面板、重要性星標
📤 Markdown/JSON 匯入匯出	彈性的資料交換格式，方便與其他工具整合
⭐ 重要性評分系統	0-10 星評分，幫你快速識別核心知識
🪶 零外部依賴	純 Python 標準函式庫實作，相容 Python 3.8+

---

🚀 快速開始

安裝

# 從 PyPI 安裝（推薦）
pip install mindtree

# 本機開發安裝
git clone https://github.com/gitstq/MindTree.git
cd MindTree
pip install -e .

五分鐘上手

# 1️⃣ 初始化知識樹
mindtree init

# 2️⃣ 新增你的第一個知識節點
mindtree add "Python 學習路線" --type concept --tags "python,學習" --content "從基礎語法到進階特性" --importance 8

# 3️⃣ 新增子節點，建構知識層級
mindtree add "基礎語法" --parent <父節點ID> --type note --tags "python,基礎" --content "變數、資料型態、控制流程"

# 4️⃣ 搜尋知識
mindtree search "python 基礎" --type note

# 5️⃣ 檢視知識樹全貌
mindtree tree --depth 3

# 6️⃣ 檢視統計面板
mindtree stats

---

📖 詳細使用指南

🌳 知識樹管理

mindtree init -- 初始化知識樹

在目前使用者目錄下建立 ~/.mindtree/ 資料目錄，用於儲存知識樹資料。

mindtree init

mindtree add -- 新增知識節點

建立一個新的知識節點，支援指定類型、標籤、父節點和內容。

# 基本用法
mindtree add "標題"

# 完整參數
mindtree add "機器學習入門" \
  --type concept \
  --tags "ml,ai,學習" \
  --content "機器學習是人工智慧的一個子領域..." \
  --importance 7 \
  --parent <父節點ID>

參數說明：

參數	說明	預設值
title	節點標題（必填）	-
--type	節點類型：note / concept / reference / task / idea	note
--tags	逗號分隔的標籤列表	空
--parent	父節點 ID	無（作為根節點）
--content	節點內容	空
--importance	重要性評分（0-10）	5

mindtree show <ID> -- 檢視節點詳情

展示指定節點的完整資訊，包括類型、標籤、重要性、內容、關聯連結等。

mindtree show <節點ID>

mindtree edit <ID> -- 編輯節點

修改已有節點的標題、內容、標籤、類型或重要性評分。

# 修改標題和內容
mindtree edit <節點ID> --title "新標題" --content "新內容"

# 修改標籤和重要性
mindtree edit <節點ID> --tags "新標籤1,新標籤2" --importance 9

# 修改節點類型
mindtree edit <節點ID> --type concept

mindtree delete <ID> -- 刪除節點

刪除指定節點。如果節點有子節點，需要使用 --recursive 參數遞迴刪除。

# 刪除葉節點
mindtree delete <節點ID>

# 遞迴刪除節點及其所有子節點
mindtree delete <節點ID> --recursive

mindtree link <ID1> <ID2> -- 建立節點關聯

在兩個節點之間建立語意關聯關係。

# 建立關聯
mindtree link <節點ID1> <節點ID2> --relation "相關"

# 其他關聯類型範例
mindtree link <ID1> <ID2> --relation "依賴"
mindtree link <ID1> <ID2> --relation "擴充"
mindtree link <ID1> <ID2> --relation "對比"

mindtree tree -- 展示知識樹

以彩色樹狀結構展示知識樹，支援指定展示深度。

# 預設展示 3 層
mindtree tree

# 指定展示深度
mindtree tree --depth 5

mindtree path <ID> -- 檢視節點路徑

展示從根節點到指定節點的完整路徑。

mindtree path <節點ID>
# 輸出範例：根節點 > 子節點 > 目標節點

---

🔍 搜尋與查詢

mindtree search -- 全文搜尋

使用 TF-IDF 演算法對知識樹進行全文搜尋，支援中英文分詞和多種過濾條件。

# 基本搜尋
mindtree search "機器學習"

# 按類型過濾
mindtree search "python" --type concept

# 按標籤過濾
mindtree search "演算法" --tags "python,資料結構"

# 限制結果數量
mindtree search "設計模式" --limit 10

# 組合使用
mindtree search "並行程式設計" --type note --tags "python,多執行緒" --limit 5

參數說明：

參數	說明	預設值
query	搜尋關鍵字（必填）	-
--type	按節點類型過濾	不過濾
--tags	按標籤過濾（逗號分隔）	不過濾
--limit	最大回傳結果數	20

mindtree tags -- 檢視所有標籤

列出知識樹中所有標籤及其使用次數，按頻率排序。

mindtree tags

mindtree recent -- 檢視最近更新

展示最近更新的知識節點列表。

# 預設顯示最近 10 筆
mindtree recent

# 指定顯示數量
mindtree recent --limit 20

---

📤 匯入匯出

mindtree export -- 匯出知識樹

將知識樹匯出為 Markdown 或 JSON 格式。

# 匯出為 Markdown
mindtree export --format md --output knowledge.md

# 匯出為 JSON
mindtree export --format json --output knowledge.json

# 匯出指定子樹
mindtree export --node <節點ID> --format md --output subtree.md

mindtree import -- 匯入知識樹

從 JSON 檔案匯入知識樹資料。

mindtree import knowledge.json

---

📊 系統指令

mindtree stats -- 統計面板

展示知識樹的統計資訊，包括節點數量、類型分佈、熱門標籤、存取頻率等。

mindtree stats

全域選項

# 指定自訂資料目錄
mindtree --data-dir /path/to/custom/dir tree

# 停用彩色輸出
mindtree --no-color search "關鍵字"

# 檢視版本資訊
mindtree --version

---

💡 設計思路與迭代規劃

設計理念

MindTree 的核心設計理念是**「讓知識管理回歸終端」**。在工具日益繁雜的今天，我們相信終端依然是最簡潔、最高效的知識管理環境：

1. 層級 > 扁平 -- 人類思維天然是層級的，樹狀結構比扁平列表更貼近認知模型
2. 搜尋 > 分類 -- 好的搜尋引擎讓你不再糾結「該放在哪個資料夾」
3. 簡單 > 複雜 -- 零依賴、純標準函式庫，安裝即用，不被工具綁架
4. 本地 > 雲端 -- 資料儲存在本地，隱私安全，離線可用

架構設計

MindTree
├── engine.py    # 核心引擎：節點管理、索引、搜尋、持久化
├── cli.py       # 命令列介面：參數解析、命令分發
└── tui.py       # 終端介面：樹狀渲染、搜尋結果、統計面板

未來規劃

• 🔌 外掛系統 -- 支援自訂節點類型和搜尋後端
• 🌐 Web UI -- 提供可選的 Web 介面用於視覺化瀏覽
• 📱 同步功能 -- 支援多裝置間的知識樹同步
• 🤖 AI 增強 -- 整合本地 LLM 實現智慧摘要與問答
• 📊 知識圖譜 -- 基於節點關聯產生視覺化知識圖譜
• 🔔 複習提醒 -- 基於艾賓浩斯遺忘曲線的間隔複習

---

📦 打包與部署指南

本機開發

# 複製倉庫
git clone https://github.com/gitstq/MindTree.git
cd MindTree

# 安裝開發依賴
pip install -e ".[dev]"

# 執行測試
pytest

# 執行測試（含覆蓋率）
pytest --cov=mindtree

建構發布包

# 安裝建構工具
pip install build

# 建構 sdist 和 wheel
python -m build

# 產生的套件在 dist/ 目錄下
ls dist/
# mindtree-1.0.0.tar.gz
# mindtree-1.0.0-py3-none-any.whl

發布到 PyPI

# 安裝 Twine
pip install twine

# 檢查套件
twine check dist/*

# 上傳到 PyPI
twine upload dist/*

系統需求

• Python >= 3.8
• 作業系統：Linux、macOS、Windows 均可
• 外部依賴：無（零依賴設計）

---

🤝 貢獻指南

我們歡迎並感謝所有形式的貢獻！無論是回報 Bug、改善文件，還是貢獻程式碼。

貢獻流程

1. 🍴 Fork 本倉庫
2. 🌿 建立特性分支：git checkout -b feature/amazing-feature
3. 💾 提交變更：git commit -m 'Add some amazing feature'
4. 📤 推送到分支：git push origin feature/amazing-feature
5. 🎉 提交 Pull Request

程式碼規範

• 遵循 PEP 8 編碼規範
• 撰寫單元測試涵蓋新功能
• 保持零外部依賴的設計原則
• 新增清晰的文件字串與註解

回報問題

如果遇到 Bug 或有功能建議，請在 GitHub Issues 中提交。

---

📄 開源授權

本專案基於 MIT License 開源。

MIT License

Copyright (c) 2024 gitstq

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

---

🎉 English

📖 Introduction

MindTree is a lightweight personal knowledge management tool built for terminal power users. It organizes your knowledge nodes in a hierarchical tree structure, features a built-in TF-IDF full-text search engine with Chinese and English tokenization support, and provides a beautiful TUI dashboard for visual exploration.

Whether you're a developer, researcher, or lifelong learner, MindTree helps you efficiently capture, organize, and retrieve your knowledge fragments right from the terminal -- building your very own second brain.

Why MindTree?

• 🌲 Tree-based Thinking -- Hierarchical structure mirrors how your brain naturally organizes knowledge, far better than flat lists
• 🔍 Smart Search -- TF-IDF algorithm + CJK/English bigram tokenization for pinpoint-accurate knowledge retrieval
• 🎨 Terminal Aesthetics -- Colorized tree views, visual search results, and statistics dashboards make the terminal beautiful
• 🪶 Zero Dependencies -- Built entirely with Python standard library. pip install and you're good to go
• 📦 Lightweight & Portable -- All data stored in a local JSON file, easy to back up and migrate

---

✨ Core Features

Feature	Description
🌳 Hierarchical Knowledge Tree	Create, edit, and delete knowledge nodes with unlimited parent-child nesting
📝 5 Node Types	note, concept, reference, task, idea -- each with its own icon and color
🔍 TF-IDF Full-Text Search	CJK/English tokenization, bigram support, tag filtering, type filtering
🔗 Node Linking	Create semantic associations between nodes to build a knowledge graph
🎨 TUI Dashboard	Colorized tree display, search result visualization, statistics panel, star ratings
📤 Markdown/JSON Import & Export	Flexible data exchange formats for integration with other tools
⭐ Importance Rating	0-10 star rating system to quickly identify your core knowledge
🪶 Zero External Dependencies	Pure Python standard library, compatible with Python 3.8+

---

🚀 Quick Start

Installation

# Install from PyPI (recommended)
pip install mindtree

# Local development install
git clone https://github.com/gitstq/MindTree.git
cd MindTree
pip install -e .

Five-Minute Tour

# 1️⃣ Initialize your knowledge tree
mindtree init

# 2️⃣ Add your first knowledge node
mindtree add "Python Learning Path" --type concept --tags "python,learning" --content "From basics to advanced features" --importance 8

# 3️⃣ Add child nodes to build hierarchy
mindtree add "Basic Syntax" --parent <parent-node-ID> --type note --tags "python,basics" --content "Variables, data types, control flow"

# 4️⃣ Search your knowledge
mindtree search "python basics" --type note

# 5️⃣ View the full tree
mindtree tree --depth 3

# 6️⃣ Check the stats dashboard
mindtree stats

---

📖 Detailed Usage Guide

🌳 Knowledge Tree Management

mindtree init -- Initialize Knowledge Tree

Creates the ~/.mindtree/ data directory in your home folder for storing knowledge tree data.

mindtree init

mindtree add -- Add a Knowledge Node

Creates a new knowledge node with support for type, tags, parent node, and content.

# Basic usage
mindtree add "Title"

# Full parameters
mindtree add "Intro to Machine Learning" \
  --type concept \
  --tags "ml,ai,learning" \
  --content "Machine learning is a subfield of artificial intelligence..." \
  --importance 7 \
  --parent <parent-node-ID>

Parameter Reference:

Parameter	Description	Default
title	Node title (required)	-
--type	Node type: note / concept / reference / task / idea	note
--tags	Comma-separated tag list	empty
--parent	Parent node ID	none (root node)
--content	Node content	empty
--importance	Importance rating (0-10)	5

mindtree show <ID> -- View Node Details

Displays the full information of a specified node, including type, tags, importance, content, linked nodes, and more.

mindtree show <node-ID>

mindtree edit <ID> -- Edit a Node

Modifies an existing node's title, content, tags, type, or importance rating.

# Update title and content
mindtree edit <node-ID> --title "New Title" --content "New content"

# Update tags and importance
mindtree edit <node-ID> --tags "tag1,tag2" --importance 9

# Change node type
mindtree edit <node-ID> --type concept

mindtree delete <ID> -- Delete a Node

Deletes a specified node. If the node has children, use the --recursive flag to remove all descendants.

# Delete a leaf node
mindtree delete <node-ID>

# Recursively delete a node and all its children
mindtree delete <node-ID> --recursive

mindtree link <ID1> <ID2> -- Link Nodes

Creates a semantic association between two nodes.

# Create a link
mindtree link <node-ID-1> <node-ID-2> --relation "related"

# Other relation type examples
mindtree link <ID1> <ID2> --relation "depends-on"
mindtree link <ID1> <ID2> --relation "extends"
mindtree link <ID1> <ID2> --relation "compares-to"

mindtree tree -- Display Knowledge Tree

Renders the knowledge tree as a colorized tree structure with configurable depth.

# Default: show 3 levels
mindtree tree

# Specify depth
mindtree tree --depth 5

mindtree path <ID> -- Show Node Path

Displays the full path from the root to the specified node.

mindtree path <node-ID>
# Example output: Root Node > Child Node > Target Node

---

🔍 Search & Query

mindtree search -- Full-Text Search

Performs full-text search on the knowledge tree using the TF-IDF algorithm with support for CJK/English tokenization and multiple filter conditions.

# Basic search
mindtree search "machine learning"

# Filter by type
mindtree search "python" --type concept

# Filter by tags
mindtree search "algorithm" --tags "python,data-structures"

# Limit results
mindtree search "design patterns" --limit 10

# Combine filters
mindtree search "concurrent programming" --type note --tags "python,multithreading" --limit 5

Parameter Reference:

Parameter	Description	Default
query	Search keywords (required)	-
--type	Filter by node type	no filter
--tags	Filter by tags (comma-separated)	no filter
--limit	Maximum number of results	20

mindtree tags -- List All Tags

Lists all tags in the knowledge tree with their usage counts, sorted by frequency.

mindtree tags

mindtree recent -- Show Recent Updates

Displays a list of the most recently updated knowledge nodes.

# Default: show last 10
mindtree recent

# Specify count
mindtree recent --limit 20

---

📤 Import & Export

mindtree export -- Export Knowledge Tree

Exports the knowledge tree to Markdown or JSON format.

# Export as Markdown
mindtree export --format md --output knowledge.md

# Export as JSON
mindtree export --format json --output knowledge.json

# Export a specific subtree
mindtree export --node <node-ID> --format md --output subtree.md

mindtree import -- Import Knowledge Tree

Imports knowledge tree data from a JSON file.

mindtree import knowledge.json

---

📊 System Commands

mindtree stats -- Statistics Dashboard

Displays knowledge tree statistics including node counts, type distribution, top tags, access frequency, and more.

mindtree stats

Global Options

# Specify a custom data directory
mindtree --data-dir /path/to/custom/dir tree

# Disable colored output
mindtree --no-color search "keywords"

# Show version information
mindtree --version

---

💡 Design Philosophy & Roadmap

Design Philosophy

MindTree's core philosophy is "bringing knowledge management back to the terminal". In an era of increasingly complex tools, we believe the terminal remains the simplest and most efficient environment for knowledge management:

1. Hierarchy over Flatness -- Human thinking is inherently hierarchical; tree structures are closer to our cognitive model than flat lists
2. Search over Categorization -- A great search engine means you never have to agonize over "which folder does this go in"
3. Simplicity over Complexity -- Zero dependencies, pure standard library, install and run, never be held hostage by your tools
4. Local over Cloud -- Data stored locally, privacy guaranteed, works offline

Architecture

MindTree
├── engine.py    # Core engine: node management, indexing, search, persistence
├── cli.py       # CLI interface: argument parsing, command dispatch
└── tui.py       # Terminal UI: tree rendering, search results, stats panel

Roadmap

• 🔌 Plugin System -- Support for custom node types and search backends
• 🌐 Web UI -- Optional web interface for visual browsing
• 📱 Sync Support -- Cross-device knowledge tree synchronization
• 🤖 AI Enhancement -- Local LLM integration for intelligent summarization and Q&A
• 📊 Knowledge Graph -- Visual knowledge graph generation based on node associations
• 🔔 Spaced Repetition -- Review reminders based on the Ebbinghaus forgetting curve

---

📦 Packaging & Deployment Guide

Local Development

# Clone the repository
git clone https://github.com/gitstq/MindTree.git
cd MindTree

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=mindtree

Building Release Packages

# Install build tools
pip install build

# Build sdist and wheel
python -m build

# Generated packages are in the dist/ directory
ls dist/
# mindtree-1.0.0.tar.gz
# mindtree-1.0.0-py3-none-any.whl

Publishing to PyPI

# Install Twine
pip install twine

# Check packages
twine check dist/*

# Upload to PyPI
twine upload dist/*

System Requirements

• Python >= 3.8
• Operating System: Linux, macOS, Windows
• External Dependencies: None (zero-dependency design)

---

🤝 Contributing Guide

We welcome and appreciate contributions of all kinds -- whether it's reporting bugs, improving documentation, or contributing code.

Contribution Workflow

1. 🍴 Fork this repository
2. 🌿 Create a feature branch: git checkout -b feature/amazing-feature
3. 💾 Commit your changes: git commit -m 'Add some amazing feature'
4. 📤 Push to the branch: git push origin feature/amazing-feature
5. 🎉 Open a Pull Request

Code Standards

• Follow PEP 8 coding conventions
• Write unit tests to cover new functionality
• Maintain the zero-dependency design principle
• Add clear docstrings and comments

Reporting Issues

If you encounter a bug or have a feature suggestion, please open an issue on GitHub Issues.

---

📄 License

This project is licensed under the MIT License.

MIT License

Copyright (c) 2024 gitstq

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

---

Made with 💚 by gitstq