evrmem 0.0.1__tar.gz

evrmem-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pink
+
+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. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

evrmem-0.0.1/MANIFEST.in

@@ -0,0 +1,4 @@
+include LICENSE
+include README.md
+include pyproject.toml
+recursive-include src/qmd *.py

evrmem-0.0.1/PKG-INFO

@@ -0,0 +1,431 @@
+Metadata-Version: 2.4
+Name: evrmem
+Version: 0.0.1
+Summary: QMD - 本地化 AI 向量记忆系统
+Author: Pink
+License: MIT
+Project-URL: Homepage, https://github.com/zhzgao/evrmem
+Project-URL: Repository, https://github.com/zhzgao/evrmem
+Project-URL: Documentation, https://zhzgao.github.io/evrmem
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: chromadb>=0.4.0
+Requires-Dist: sentence-transformers>=2.2.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: black>=24.0.0; extra == "dev"
+Requires-Dist: isort>=5.12.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+
+# evrmem
+
+> QMD - 本地化 AI 向量记忆系统 / Fully Local AI Vector Memory System
+
+[![GitHub stars](https://img.shields.io/github/stars/zhzgao/evrmem?style=social)](https://github.com/zhzgao/evrmem/stargazers)
+[![GitHub forks](https://img.shields.io/github/forks/zhzgao/evrmem?style=social)](https://github.com/zhzgao/evrmem/network/members)
+[![PyPI version](https://img.shields.io/pypi/v/evrmem?color=blue)](https://pypi.org/project/evrmem/)
+[![Python](https://img.shields.io/badge/python-3.9+-green.svg)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![GitHub Actions Status](https://img.shields.io/github/actions/workflow/status/zhzgao/evrmem/deploy-pages.yml)](https://github.com/zhzgao/evrmem/actions)
+[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://zhzgao.github.io/evrmem)
+[![Offline](https://img.shields.io/badge/100%25-Offline-green)](https://github.com/zhzgao/evrmem)
+[![Chinese](https://img.shields.io/badge/中文-优化-orange)](https://github.com/zhzgao/evrmem)
+
+---
+
+📖 **在线文档**: https://zhzgao.github.io/evrmem
+
+---
+
+## English
+
+### What is evrmem?
+
+evrmem (pronounced "e-vee-are-mem") is a **fully local AI vector memory system** designed for developers and AI agents. It stores, retrieves, and reasons over personal knowledge using semantic vector search — no cloud, no API keys, 100% offline.
+
+Built on [ChromaDB](https://www.trychroma.com/) + [text2vec-base-chinese](https://huggingface.co/shibing624/text2vec-base-chinese), evrmem is optimized for **Chinese semantic understanding** and works entirely offline after initial model setup.
+
+### Features
+
+- **Semantic Search** — Natural language queries with Chinese-optimized embeddings
+- **Structured Query** — Filter by project, date, tags, or type
+- **RAG Retrieval** — Generate context-augmented prompts for LLMs
+- **100% Offline** — Works without internet after model is cached
+- **Single Command CLI** — `evrmem add / search / rag / query / stats`
+- **Python API** — Embed in any Python project
+
+### Quick Start
+
+```bash
+# Install (from source)
+pip install -e .
+
+# Add a memory
+evrmem add "React StrictMode causes Form.useForm warning" --project mes-demo --tags react,antd
+
+# Search memories
+evrmem search "React form warning fix"
+
+# RAG: generate LLM prompt with context
+evrmem rag "how to fix the form warning" --prompt
+
+# View stats
+evrmem stats
+
+# Structured query
+evrmem query --project mes-demo
+```
+
+### Installation
+
+#### Option A: pip install (recommended when published)
+
+```bash
+pip install evrmem
+```
+
+#### Option B: Install from source
+
+```bash
+git clone https://github.com/pink/evrmem.git
+cd evrmem
+pip install -e .
+```
+
+#### Dependencies
+
+- Python 3.9+
+- `chromadb` — Vector database
+- `sentence-transformers` — Embedding model
+- `pyyaml` — Config file support
+
+Embedding model (`shibing624/text2vec-base-chinese`, ~400MB) is downloaded automatically on first run.
+
+### Configuration
+
+Config file `config.yaml` (in project root or `~/.evrmem/config.yaml`):
+
+```yaml
+vector_db:
+  persist_directory: "~/.evrmem/data/qmd_memory"
+
+embedding:
+  model_name: "shibing624/text2vec-base-chinese"  # HuggingFace model
+  cache_folder: "~/.evrmem/models"                  # Local model cache
+  device: "cpu"                                     # or "cuda"
+
+rag:
+  top_k: 5
+  min_similarity: 0.5
+
+logging:
+  level: "WARNING"
+```
+
+Environment variables override config file (highest priority):
+
+| Variable | Config Key | Description |
+|----------|-----------|-------------|
+| `EVREM_MODEL_NAME` | `embedding.model_name` | HuggingFace model name |
+| `EVREM_LOCAL_MODEL` | `embedding.local_path` | Local model path (highest priority) |
+| `EVREM_DEVICE` | `embedding.device` | `cpu` or `cuda` |
+| `EVREM_DATA_DIR` | `vector_db.persist_directory` | Data directory |
+| `EVREM_TOP_K` | `rag.top_k` | Default retrieval count |
+| `EVREM_LOG_LEVEL` | `logging.level` | `DEBUG`, `INFO`, `WARNING`, `ERROR` |
+
+### CLI Reference
+
+```bash
+# Add memory
+evrmem add "content here" [-p project] [-t tags] [-d date] [-f file]
+
+# Semantic search
+evrmem search "query" [-k top_k] [-s min_similarity] [-v]
+evrmem search              # Interactive mode
+
+# RAG retrieval
+evrmem rag "query" [-k top_k] [-s min_similarity] [-p]  # -p = generate full prompt
+evrmem rag                # Interactive mode
+
+# Structured query
+evrmem query [--project name] [--date YYYY-MM-DD] [--tag tag] [--type type]
+evrmem query --list-projects
+evrmem query --list-tags
+
+# Stats & init
+evrmem stats
+evrmem init
+
+# Help & version
+evrmem --help
+evrmem -v
+```
+
+### Python API
+
+```python
+from qmd.core.vector_db import vector_db
+from qmd.core.embedding import get_embedding_model
+
+# Add
+memory_id = vector_db.add_memory(
+    "React StrictMode causes Form.useForm warning",
+    metadata={"project": "mes-demo", "tags": "react,antd", "date": "2026-03-27"}
+)
+
+# Semantic search
+results = vector_db.search("react antd form warning", top_k=5)
+
+# Metadata query
+results = vector_db.query_by_metadata({"project": "mes-demo"})
+
+# Get embedding model directly
+emb = get_embedding_model()
+vec = emb.encode("hello world")
+print(f"Dimension: {emb.dimension}")  # 768
+```
+
+### Architecture
+
+```
+User Input / CLI
+      │
+      ▼
+┌──────────────┐
+│   qmd.cli    │  ← argparse-based unified CLI
+└──────┬───────┘
+       │
+       ▼
+┌──────────────┐     ┌────────────────────────────┐
+│  VectorDB    │────▶│ ChromaDB (PersistentClient) │
+│  (singleton) │     └────────────────────────────┘
+└──────┬───────┘
+       │ embed()
+       ▼
+┌──────────────────────────────────────────────────┐
+│ EmbeddingModel (lazy-loaded)                     │
+│  ├─ SentenceTransformer (text2vec-base-chinese)  │
+│  ├─ _resolve_local_model() [offline support]    │
+│  └─ local_files_only=True [no network calls]     │
+└──────────────────────────────────────────────────┘
+```
+
+### License
+
+MIT — see [LICENSE](LICENSE).
+
+---
+
+## 中文
+
+### 什么是 evrmem？
+
+evrmem 是一个**完全本地化的 AI 向量记忆系统**，专为开发者和 AI 智能体设计。通过语义向量搜索存储、检索和推理个人知识——无需云服务、无需 API Key、100% 离线运行。
+
+基于 [ChromaDB](https://www.trychroma.com/) + [text2vec-base-chinese](https://huggingface.co/shibing624/text2vec-base-chinese) 构建，针对**中文语义理解**深度优化，首次配置后完全离线工作。
+
+### 特性
+
+- **语义搜索** — 自然语言查询，中文语义优先
+- **结构化查询** — 按项目、日期、标签等维度筛选
+- **RAG 增强** — 生成带上下文的 LLM 提示词
+- **100% 离线** — 模型缓存后无需网络
+- **单命令 CLI** — `evrmem add / search / rag / query / stats`
+- **Python API** — 嵌入任意 Python 项目
+
+### 快速开始
+
+```bash
+# 从源码安装
+pip install -e .
+
+# 添加记忆
+evrmem add "React StrictMode 导致 Form.useForm 警告" --project mes-demo --tags react,antd
+
+# 语义搜索
+evrmem search "React 表单警告修复"
+
+# RAG：生成带上下文的 LLM 提示词
+evrmem rag "如何修复表单警告" --prompt
+
+# 查看统计
+evrmem stats
+
+# 结构化查询
+evrmem query --project mes-demo
+```
+
+### 安装
+
+#### 方式 A：pip 安装（发布后推荐）
+
+```bash
+pip install evrmem
+```
+
+#### 方式 B：从源码安装
+
+```bash
+git clone https://github.com/pink/evrmem.git
+cd evrmem
+pip install -e .
+```
+
+#### 依赖
+
+- Python 3.9+
+- `chromadb` — 向量数据库
+- `sentence-transformers` — Embedding 模型
+- `pyyaml` — 配置文件支持
+
+Embedding 模型（`shibing624/text2vec-base-chinese`，约 400MB）首次运行自动下载。
+
+### 配置
+
+配置文件 `config.yaml`（项目根目录或 `~/.evrmem/config.yaml`）：
+
+```yaml
+vector_db:
+  persist_directory: "~/.evrmem/data/qmd_memory"
+
+embedding:
+  model_name: "shibing624/text2vec-base-chinese"  # HuggingFace 模型名
+  cache_folder: "~/.evrmem/models"                  # 本地模型缓存目录
+  device: "cpu"                                     # 或 "cuda"
+
+rag:
+  top_k: 5
+  min_similarity: 0.5
+
+logging:
+  level: "WARNING"
+```
+
+环境变量优先级最高（覆盖配置文件）：
+
+| 变量 | 配置项 | 说明 |
+|------|--------|------|
+| `EVREM_MODEL_NAME` | `embedding.model_name` | HuggingFace 模型名 |
+| `EVREM_LOCAL_MODEL` | `embedding.local_path` | 本地模型路径（优先级最高） |
+| `EVREM_DEVICE` | `embedding.device` | `cpu` 或 `cuda` |
+| `EVREM_DATA_DIR` | `vector_db.persist_directory` | 数据目录 |
+| `EVREM_TOP_K` | `rag.top_k` | 默认检索条数 |
+| `EVREM_LOG_LEVEL` | `logging.level` | `DEBUG`、`INFO`、`WARNING`、`ERROR` |
+
+### CLI 命令参考
+
+```bash
+# 添加记忆
+evrmem add "记忆内容" [-p 项目名] [-t 标签] [-d 日期] [-f 文件路径]
+
+# 语义搜索
+evrmem search "查询内容" [-k 返回条数] [-s 最小相似度] [-v 详细输出]
+evrmem search              # 交互模式
+
+# RAG 检索
+evrmem rag "查询内容" [-k 条数] [-s 相似度] [-p 生成完整提示词]
+evrmem rag                # 交互模式
+
+# 结构化查询
+evrmem query [--project 项目名] [--date YYYY-MM-DD] [--tag 标签] [--type 类型]
+evrmem query --list-projects   # 列出所有项目
+evrmem query --list-tags       # 列出所有标签
+
+# 统计与初始化
+evrmem stats   # 系统状态
+evrmem init    # 初始化/查看状态
+
+# 帮助与版本
+evrmem --help
+evrmem -v
+```
+
+### Python API
+
+```python
+from qmd.core.vector_db import vector_db
+from qmd.core.embedding import get_embedding_model
+
+# 添加记忆
+memory_id = vector_db.add_memory(
+    "React StrictMode 导致 Form.useForm 警告",
+    metadata={"project": "mes-demo", "tags": "react,antd", "date": "2026-03-27"}
+)
+
+# 语义搜索
+results = vector_db.search("react antd form warning", top_k=5)
+
+# 按元数据查询
+results = vector_db.query_by_metadata({"project": "mes-demo"})
+
+# 直接使用 Embedding 模型
+emb = get_embedding_model()
+vec = emb.encode("你好世界")
+print(f"向量维度: {emb.dimension}")  # 768
+```
+
+### 技术架构
+
+```
+用户输入 / CLI 命令
+      │
+      ▼
+┌──────────────┐
+│   qmd.cli    │  ← 基于 argparse 的统一 CLI 入口
+└──────┬───────┘
+       │
+       ▼
+┌──────────────┐     ┌────────────────────────────┐
+│  VectorDB    │────▶│ ChromaDB (PersistentClient) │
+│  (单例模式)   │     └────────────────────────────┘
+└──────┬───────┘
+       │ embed()
+       ▼
+┌──────────────────────────────────────────────────┐
+│ EmbeddingModel（延迟加载）                        │
+│  ├─ SentenceTransformer (text2vec-base-chinese)  │
+│  ├─ _resolve_local_model() [离线路径解析]         │
+│  └─ local_files_only=True [零网络请求]           │
+└──────────────────────────────────────────────────┘
+```
+
+### 项目结构
+
+```
+evrmem/
+├── src/qmd/              # 源码包
+│   ├── __init__.py
+│   ├── __main__.py       # python -m qmd 入口
+│   ├── cli.py             # CLI 主逻辑
+│   ├── core/
+│   │   ├── config.py      # 配置加载器
+│   │   ├── embedding.py   # Embedding 模型封装
+│   │   └── vector_db.py   # ChromaDB 封装
+│   └── utils/
+│       └── console.py     # 跨平台控制台编码
+├── docs/                 # 开发文档
+│   ├── index.md          # 文档导航
+│   └── DEVELOPMENT.md    # 开发指南
+├── config.yaml           # 配置文件
+├── pyproject.toml        # pip 包配置
+├── LICENSE               # MIT 协议
+├── README.md             # 本文档（中英双语）
+├── CONTRIBUTING.md        # 贡献指南
+├── CHANGELOG.md          # 更新日志
+├── evrmem.bat            # Windows 快捷命令
+└── evrmem.sh             # Unix 快捷命令
+```
+
+### 协议
+
+MIT — 详见 [LICENSE](LICENSE)。