Metadata-Version: 2.4
Name: obsidian-dev-memory
Version: 1.1.0
Summary: 三层知识架构 MCP Server — 规范手册 + 知识网络 + 原始资料，越用越智能的开发知识库
Project-URL: Homepage, https://github.com/Frankly666/dev-memory
Project-URL: Repository, https://github.com/Frankly666/dev-memory
Project-URL: Issues, https://github.com/Frankly666/dev-memory/issues
Author: franklynxu
License-Expression: MIT
License-File: LICENSE
Keywords: ai,developer-tools,knowledge-base,mcp,obsidian,semantic-search
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: chromadb>=0.4.22
Requires-Dist: click>=8.1.0
Requires-Dist: mcp[cli]>=1.0.0
Requires-Dist: python-frontmatter>=1.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: requests>=2.31.0
Requires-Dist: sentence-transformers>=2.2.2
Provides-Extra: dev
Requires-Dist: pytest-mock>=3.12.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: requests-mock>=1.11.0; extra == 'dev'
Description-Content-Type: text/markdown

# Dev Memory — 三层知识架构 MCP Server

> 让 AI 记住你的每一次经验。三层架构（规范手册 + 知识网络 + 原始资料）实现越用越智能的知识复利。

[![PyPI](https://img.shields.io/pypi/v/obsidian-dev-memory.svg)](https://pypi.org/project/obsidian-dev-memory/)
[![npm](https://img.shields.io/npm/v/obsidian-dev-memory.svg)](https://www.npmjs.com/package/obsidian-dev-memory)
[![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://www.python.org/)
[![MCP](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)

## 一键接入

### 第一步：安装 Python 环境

> Dev Memory 底层使用 Python 运行。如果你已有 Python 3.10+ 环境，可跳过此步。

**推荐：安装 uv（一行命令，自动管理 Python，无需手动装 Python）**

```bash
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# 或用 Homebrew (macOS)
brew install uv
```

安装后终端输入 `uvx --version` 验证成功。`uvx` 会自动下载并管理 Python，**你不需要单独安装 Python**。

<details>
<summary>🔧 其他方式安装 Python 3.10+</summary>

| 系统 | 安装命令 |
|------|---------|
| **macOS** | `brew install python@3.12` 或去 [python.org](https://www.python.org/downloads/) 下载 |
| **Windows** | `winget install Python.Python.3.12` 或去 [python.org](https://www.python.org/downloads/) 下载 |
| **Ubuntu/Debian** | `sudo apt install python3 python3-pip` |

安装后终端输入 `python3 --version` 验证（需显示 3.10 以上）。

</details>

### 第二步：找到你的 Obsidian Vault 路径

打开 Obsidian → 点击左下角 **⚙️ 设置** → **关于** → 复制 **Vault 路径**。

<details>
<summary>📍 各系统常见路径参考</summary>

| 系统 | 常见路径 |
|------|---------|
| **macOS** | `~/Documents/MyVault` 或 `~/Library/Mobile Documents/iCloud~md~obsidian/Documents/MyVault` |
| **Windows** | `C:\Users\你的用户名\Documents\MyVault` |
| **Linux** | `~/Documents/MyVault` 或 `~/obsidian/MyVault` |

</details>

### 第三步：复制配置到你的 AI IDE

选择你的 IDE，复制配置，**只需要改 Vault 路径**：

<details open>
<summary><b>🟢 方式一：uvx（推荐，最简单）</b></summary>

> 前提：已安装 uv（第一步）

**Cursor** — 编辑 `~/.cursor/mcp.json`：
```json
{
  "mcpServers": {
    "dev-memory": {
      "command": "uvx",
      "args": ["--from", "obsidian-dev-memory", "dev-memory-mcp"],
      "env": {
        "DEV_MEMORY_VAULT_PATH": "/改成你的/Obsidian/Vault路径"
      }
    }
  }
}
```

**Claude Code:**
```bash
claude mcp add dev-memory -e DEV_MEMORY_VAULT_PATH=/改成你的/Obsidian/Vault路径 -- uvx --from obsidian-dev-memory dev-memory-mcp
```

**CodeBuddy** — MCP 设置面板中添加：
- **名称**: `dev-memory`
- **命令**: `uvx`
- **参数**: `--from obsidian-dev-memory dev-memory-mcp`
- **环境变量**: `DEV_MEMORY_VAULT_PATH` = `你的 Vault 路径`

</details>

<details>
<summary><b>🔵 方式二：npx（有 Node.js 环境时可用）</b></summary>

> npx wrapper 会自动检测 uvx/pipx/pip 并启动 Python 端，底层仍需 Python 环境。

**Cursor** — 编辑 `~/.cursor/mcp.json`：
```json
{
  "mcpServers": {
    "dev-memory": {
      "command": "npx",
      "args": ["-y", "obsidian-dev-memory"],
      "env": {
        "DEV_MEMORY_VAULT_PATH": "/改成你的/Obsidian/Vault路径"
      }
    }
  }
}
```

**Claude Code:**
```bash
claude mcp add dev-memory -e DEV_MEMORY_VAULT_PATH=/改成你的/Obsidian/Vault路径 -- npx -y obsidian-dev-memory
```

</details>

<details>
<summary><b>⚪ 方式三：pip 全局安装</b></summary>

```bash
pip install obsidian-dev-memory
```

然后配置 IDE：
```json
{
  "mcpServers": {
    "dev-memory": {
      "command": "dev-memory-mcp",
      "env": {
        "DEV_MEMORY_VAULT_PATH": "/改成你的/Obsidian/Vault路径"
      }
    }
  }
}
```

</details>

<details>
<summary><b>⚪ 方式四：从源码安装</b></summary>

```bash
git clone https://github.com/Frankly666/dev-memory.git
cd dev-memory
pip install -e .
```

</details>

### 第四步：开始使用

重启 IDE，在对话中直接说：

```
帮我记住刚才解决的 Docker DNS 问题
```

就这样，没有第四步。🎉

---

## 环境变量配置

通过 MCP 配置的 `env` 字段传入，**无需运行 init 命令**：

| 环境变量 | 说明 | 必填 |
|---------|------|------|
| `DEV_MEMORY_VAULT_PATH` | Obsidian Vault 根目录绝对路径 | ✅ |
| `DEV_MEMORY_API_KEY` | Obsidian Local REST API 密钥 | 可选 |
| `DEV_MEMORY_DATA_DIR` | 数据存储目录（默认 `~/.dev-memory`） | 可选 |

首次启动时会自动在 Vault 中创建 `dev-memory/` 目录结构，无需手动初始化。

---

## 支持的 AI IDE

| IDE | 配置方式 |
|-----|---------|
| **Claude Code** | `claude mcp add` 命令 |
| **Cursor** | `~/.cursor/mcp.json` |
| **CodeBuddy** | MCP 设置面板 |
| **Windsurf** | MCP 设置面板 |
| 其他 MCP 客户端 | stdio 协议通用接入 |

> 详细配置步骤见 [MCP_SETUP.md](./MCP_SETUP.md)

---

## 提供的 MCP Tools

### v2 新增（推荐使用）

| 工具 | 功能 | 说明 |
|------|------|------|
| `ingest_knowledge` | 智能存储知识 | 搜索→判重→决策（新建/更新/合并）→维护关联 |
| `store_reference` | 存储原始资料 | 严格保留原文，AI 注解与原文分区 |
| `get_rules` | 获取工作规范 | 加载 RULES.md + taxonomy.yaml |
| `update_rules` | 更新工作规范 | 用户和 AI 共同维护规范 |
| `update_knowledge` | 更新知识条目 | 追加方案、调整成熟度/置信度 |
| `get_hub` | 获取主题聚合页 | 查看某主题下的知识导航 |
| `evolve_knowledge` | 触发知识演化 | 归纳 concept、更新 hub |

### 保留的 v1 Tools

| 工具 | 功能 | 说明 |
|------|------|------|
| `memorize` | 记忆开发经验 | 内部已升级为智能判重（兼容 v1） |
| `search_knowledge` | 语义搜索知识库 | 增强：返回关联上下文 |
| `list_tags` | 列出知识标签 | 标签分布和频次 |
| `get_profile` | 开发者画像 | 技术偏好分析 |
| `sync_vault` | 同步索引 | 增量/全量同步 |
| `get_stats` | 知识库统计 | 含原始资料和规范状态 |

---

## 使用示例

安装后，直接在 AI IDE 中自然语言对话：

```
你: 帮我记住刚才解决的 Docker DNS 问题
AI: ✅ 已记忆「Docker 容器 DNS 解析失败」，标签: docker, dns, 网络

你: 之前有遇到过 K8s Pod 重启的问题吗？
AI: 找到 3 条相关经验：
    1. K8s Pod CrashLoopBackOff 排查 (相关度: 0.89)
    2. 容器 OOMKilled 内存泄漏排查 (相关度: 0.76)
    ...

你: 分析一下我的开发风格
AI: 你主要关注后端基础设施，技术栈以 Go + Docker + K8s 为主...
```

---

## 前置要求

1. **Python 3.10+**（必须）— 推荐安装 [uv](https://docs.astral.sh/uv/) 自动管理 Python 环境
2. **Obsidian**（桌面端，用于存储知识）
3. **Obsidian Local REST API 插件**（可选，启用后提供全文搜索 + 实时同步）

> **为什么需要 Python？** Dev Memory 使用 `sentence-transformers` 做本地语义搜索（理解你的查询意图，而非简单关键词匹配），使用 `ChromaDB` 做本地向量索引。这些 AI/ML 库目前只有 Python 生态提供。安装 `uv` 后一切自动管理，无需手动操心 Python。

## 高级：手动初始化

如果你不想用环境变量，也可以手动初始化：

```bash
# 安装
pip install obsidian-dev-memory

# 初始化（指定你的 Obsidian Vault 路径）
dev-memory init --vault-path /path/to/your/obsidian/vault

# 可选：配置 Obsidian API 密钥
dev-memory init --vault-path /path/to/vault --api-key YOUR_API_KEY
```

配置文件保存在 `~/.dev-memory/config.yaml`，可随时编辑。

## CLI 命令

除 MCP 接口外，也可通过命令行直接使用：

```bash
dev-memory add --title "解决XX问题" --problem "描述" --solution "方案"
dev-memory search "React 闭包问题"
dev-memory sync          # 同步索引
dev-memory profile       # 开发者画像
dev-memory stats         # 统计信息
```

---

## 架构

```
AI IDE (Claude Code / Cursor / CodeBuddy)
    │ stdio (MCP 协议)
    ▼
┌──────────────────────────────────────┐
│ Dev Memory MCP Server v2             │
│ (13 个 MCP Tools)                    │
├──────────────────────────────────────┤
│ 第一层: 规范手册层                     │
│   RulebookManager                    │
│   RULES.md + taxonomy.yaml           │
├──────────────────────────────────────┤
│ 第二层: 知识网络层                     │
│   KnowledgeEngine                    │
│   搜索→判重→决策→关联→归纳            │
│   solutions/ + concepts/ + _hubs/    │
├──────────────────────────────────────┤
│ 第三层: 原始资料层                     │
│   ReferenceManager                   │
│   原文存储 + AI 注解 + 溯源链         │
│   references/                        │
├──────────────────────────────────────┤
│ 基础设施: Obsidian + ChromaDB         │
└──────────────────────────────────────┘
```

## 开发

```bash
git clone https://github.com/Frankly666/dev-memory.git
cd dev-memory
pip install -e ".[dev]"
pytest
```

## License

[MIT](./LICENSE)
