hy-memory 1.0.0__tar.gz

hy_memory-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 HY Memory Contributors
+
+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.

hy_memory-1.0.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: hy-memory
+Version: 1.0.0
+Summary: HY Memory - Intelligent hierarchical memory system for LLM agents
+Author: alvinfei
+License: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic
+Requires-Dist: numpy
+Requires-Dist: openai
+Requires-Dist: python-dotenv
+Requires-Dist: pyyaml
+Requires-Dist: chromadb
+Requires-Dist: langdetect
+Provides-Extra: qdrant
+Requires-Dist: qdrant-client; extra == "qdrant"
+Provides-Extra: faiss
+Requires-Dist: faiss-cpu; extra == "faiss"
+Provides-Extra: graph
+Requires-Dist: neo4j; extra == "graph"
+Requires-Dist: kuzu; extra == "graph"
+Provides-Extra: redis
+Requires-Dist: redis; extra == "redis"
+Provides-Extra: anthropic
+Requires-Dist: anthropic; extra == "anthropic"
+Provides-Extra: ml
+Requires-Dist: scikit-learn; extra == "ml"
+Provides-Extra: all
+Requires-Dist: chromadb; extra == "all"
+Requires-Dist: qdrant-client; extra == "all"
+Requires-Dist: faiss-cpu; extra == "all"
+Requires-Dist: kuzu; extra == "all"
+Requires-Dist: neo4j; extra == "all"
+Requires-Dist: redis; extra == "all"
+Requires-Dist: anthropic; extra == "all"
+Requires-Dist: scikit-learn; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: httpx; extra == "dev"
+Dynamic: license-file
+
+# HY Memory
+
+**Intelligent hierarchical memory system for LLM agents.**
+
+HY Memory provides a production-grade memory layer for AI agents with LLM-driven extraction, semantic search, multi-layer knowledge representation, and graph-based schema inference.
+
+## Features
+
+- **7-Layer Memory Architecture** — From raw facts (L1) to behavioral schemas (L6) and intentions (L7)
+- **LLM-Driven Extraction** — Automatically extracts structured memories from conversations
+- **Semantic Search** — Vector similarity search across all memory layers
+- **Graph Knowledge** — Neo4j/Kuzu graph store for schema and intention inference (System 2)
+- **Evolution Chains** — Tracks how memories evolve over time via supersedes links
+- **Multiple Backends** — Qdrant, ChromaDB, FAISS for vectors; Neo4j, Kuzu for graphs
+- **OpenAI-Compatible** — Works with any LLM that supports the OpenAI API format (DeepSeek, Qwen, Claude, etc.)
+
+## Quick Start
+
+```bash
+pip install hy-memory
+```
+
+```python
+from hy_memory import HyMemoryClient
+
+client = HyMemoryClient(mode="lite")
+
+# Write
+client.add("I love sci-fi movies, especially Interstellar", user_id="user_1")
+
+# Search
+results = client.search("What movies does the user like?", user_id="user_1")
+for mem in results["memories"]:
+    print(f"  [{mem['score']:.2f}] {mem['content']}")
+
+client.close()
+```
+
+## Configuration
+
+HY Memory is configured via environment variables. Minimal setup:
+
+```bash
+export MEMORY_LLM_API_KEY="sk-your-key"
+export MEMORY_LLM_BASE_URL="https://api.deepseek.com"   # or any OpenAI-compatible endpoint
+export MEMORY_LLM_MODEL="deepseek-chat"
+
+export MEMORY_EMBEDDER_API_KEY="sk-your-key"
+export MEMORY_EMBEDDER_BASE_URL="https://api.openai.com/v1"
+export MEMORY_EMBEDDER_MODEL="text-embedding-3-small"
+```
+
+Or copy `.env.example` and fill in your values:
+
+```bash
+cp .env.example .env
+```
+
+See [docs/env_reference.md](docs/env_reference.md) for all available options.
+
+## Modes
+
+| Mode | Layers | Graph | Best For |
+|------|--------|-------|----------|
+| **lite** | L0-L4 (facts + identity) | No | Simple chatbots, quick setup |
+| **pro** | L0-L5 (+ knowledge) | Optional | Knowledge-heavy applications |
+| **ultra** | L0-L7 (+ schema + intention) | Yes | Full cognitive architecture |
+
+## Vector Store Backends
+
+| Backend | Install | Config |
+|---------|---------|--------|
+| **ChromaDB** (default) | included | `MEMORY_VECTOR_STORE=chroma` |
+| **Qdrant** | `pip install hy-memory[qdrant]` | `MEMORY_VECTOR_STORE=qdrant` |
+| **FAISS** | `pip install hy-memory[faiss]` | `MEMORY_VECTOR_STORE=faiss` |
+
+## Graph Store Backends (Ultra mode)
+
+| Backend | Install | Config |
+|---------|---------|--------|
+| **Kuzu** (default) | included | `MEMORY_GRAPH_PROVIDER=kuzu` |
+| **Neo4j** | `pip install hy-memory[graph]` | `MEMORY_GRAPH_PROVIDER=neo4j` |
+
+## Documentation
+
+- [Usage Guide](docs/usage.md) — Detailed API documentation and examples
+- [Environment Reference](docs/env_reference.md) — All configuration options
+- [Contributing](CONTRIBUTING.md) — How to contribute
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

hy_memory-1.0.0/README.md

@@ -0,0 +1,92 @@
+# HY Memory
+
+**Intelligent hierarchical memory system for LLM agents.**
+
+HY Memory provides a production-grade memory layer for AI agents with LLM-driven extraction, semantic search, multi-layer knowledge representation, and graph-based schema inference.
+
+## Features
+
+- **7-Layer Memory Architecture** — From raw facts (L1) to behavioral schemas (L6) and intentions (L7)
+- **LLM-Driven Extraction** — Automatically extracts structured memories from conversations
+- **Semantic Search** — Vector similarity search across all memory layers
+- **Graph Knowledge** — Neo4j/Kuzu graph store for schema and intention inference (System 2)
+- **Evolution Chains** — Tracks how memories evolve over time via supersedes links
+- **Multiple Backends** — Qdrant, ChromaDB, FAISS for vectors; Neo4j, Kuzu for graphs
+- **OpenAI-Compatible** — Works with any LLM that supports the OpenAI API format (DeepSeek, Qwen, Claude, etc.)
+
+## Quick Start
+
+```bash
+pip install hy-memory
+```
+
+```python
+from hy_memory import HyMemoryClient
+
+client = HyMemoryClient(mode="lite")
+
+# Write
+client.add("I love sci-fi movies, especially Interstellar", user_id="user_1")
+
+# Search
+results = client.search("What movies does the user like?", user_id="user_1")
+for mem in results["memories"]:
+    print(f"  [{mem['score']:.2f}] {mem['content']}")
+
+client.close()
+```
+
+## Configuration
+
+HY Memory is configured via environment variables. Minimal setup:
+
+```bash
+export MEMORY_LLM_API_KEY="sk-your-key"
+export MEMORY_LLM_BASE_URL="https://api.deepseek.com"   # or any OpenAI-compatible endpoint
+export MEMORY_LLM_MODEL="deepseek-chat"
+
+export MEMORY_EMBEDDER_API_KEY="sk-your-key"
+export MEMORY_EMBEDDER_BASE_URL="https://api.openai.com/v1"
+export MEMORY_EMBEDDER_MODEL="text-embedding-3-small"
+```
+
+Or copy `.env.example` and fill in your values:
+
+```bash
+cp .env.example .env
+```
+
+See [docs/env_reference.md](docs/env_reference.md) for all available options.
+
+## Modes
+
+| Mode | Layers | Graph | Best For |
+|------|--------|-------|----------|
+| **lite** | L0-L4 (facts + identity) | No | Simple chatbots, quick setup |
+| **pro** | L0-L5 (+ knowledge) | Optional | Knowledge-heavy applications |
+| **ultra** | L0-L7 (+ schema + intention) | Yes | Full cognitive architecture |
+
+## Vector Store Backends
+
+| Backend | Install | Config |
+|---------|---------|--------|
+| **ChromaDB** (default) | included | `MEMORY_VECTOR_STORE=chroma` |
+| **Qdrant** | `pip install hy-memory[qdrant]` | `MEMORY_VECTOR_STORE=qdrant` |
+| **FAISS** | `pip install hy-memory[faiss]` | `MEMORY_VECTOR_STORE=faiss` |
+
+## Graph Store Backends (Ultra mode)
+
+| Backend | Install | Config |
+|---------|---------|--------|
+| **Kuzu** (default) | included | `MEMORY_GRAPH_PROVIDER=kuzu` |
+| **Neo4j** | `pip install hy-memory[graph]` | `MEMORY_GRAPH_PROVIDER=neo4j` |
+
+## Documentation
+
+- [Usage Guide](docs/usage.md) — Detailed API documentation and examples
+- [Environment Reference](docs/env_reference.md) — All configuration options
+- [Contributing](CONTRIBUTING.md) — How to contribute
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

hy_memory-1.0.0/hy_memory/__init__.py

@@ -0,0 +1,146 @@
+"""
+HY Memory - 核心 SDK
+
+工业级智能体记忆系统核心框架。
+
+快速开始:
+    export OPENAI_API_KEY="sk-your-key-here"
+
+    from hy_memory import HyMemoryClient
+
+    # 最简用法 — 只需设置 OPENAI_API_KEY 环境变量
+    client = HyMemoryClient(user_id="test_user")
+    client.add("用户喜欢科幻电影")
+    results = client.search("用户喜欢什么？")
+    client.close()
+
+默认配置:
+    - embedder: OpenAI text-embedding-3-small (1536 维)
+    - llm: OpenAI gpt-4.1-nano
+    - vector_store: Chroma 本地嵌入式 (零外部依赖)
+
+    只需设置 OPENAI_API_KEY 环境变量即可运行。
+
+    # 自定义配置
+    client = HyMemoryClient.from_config({
+        "vector_store": {"provider": "qdrant"},
+        "graph_store": {
+            "provider": "neo4j",
+            "url": "bolt://localhost:7687",
+            "username": "neo4j",
+            "password": "password",
+        },
+        "enable_graph": True,
+    }, user_id="test_user")
+
+数据隔离 (两级):
+    - user_id:  一级 key — 每个用户唯一的记忆库
+    - agent_id: 二级 key — 同一用户下不同 Agent 场景的隔离
+
+安装方式:
+    pip install hy-memory          # 核心依赖 (含 Chroma，开箱即用)
+    pip install hy-memory[qdrant]  # + Qdrant 向量库
+    pip install hy-memory[faiss]   # + FAISS 向量库
+    pip install hy-memory[all]     # 包含所有可选依赖
+"""
+
+try:
+    from importlib.metadata import version as _get_version
+    __version__ = _get_version("hy-memory")
+except Exception:
+    __version__ = "1.0.0"
+
+# ====== 用户级 API（推荐） ======
+from .client import HyMemoryClient
+from .inspector import MemoryInspector
+
+# ====== 配置 ======
+from .config import MemoryConfig
+
+# ====== 高级 API（按需使用） ======
+from .pipelines import (
+    ComponentFactory,
+    PipelineConfig,
+    WritePipeline,
+    ReadPipeline,
+    ChatMessage,
+    WriteRequest,
+    WriteResponse,
+    ReadRequest,
+    ReadResponse,
+)
+
+# ====== 数据模型 ======
+from .models import (
+    MemoryLayer,
+    MemoryNode,
+    MemoryEntry,
+    MemoryMetadata,
+    MemoryScore,
+    MemoryInputType,
+    AgentProcessMode,
+    TaskStatus,
+    DeleteScope,
+    QAPair,
+    AddRequest,
+    AddResponse,
+    AsyncAddResponse,
+    RecallRequest,
+    RecallResponse,
+    UpdateRequest,
+    UpdateResponse,
+    DeleteRequest,
+    DeleteResponse,
+    BatchDeleteRequest,
+    BatchDeleteResponse,
+    GetRequest,
+    GetResponse,
+    ListRequest,
+    ListResponse,
+)
+
+
+__all__ = [
+    "__version__",
+    # 用户级 API
+    "HyMemoryClient",
+    "MemoryInspector",
+    # 配置
+    "MemoryConfig",
+    # 高级 API
+    "ComponentFactory",
+    "PipelineConfig",
+    "WritePipeline",
+    "ReadPipeline",
+    "ChatMessage",
+    "WriteRequest",
+    "WriteResponse",
+    "ReadRequest",
+    "ReadResponse",
+    # 数据模型
+    "MemoryLayer",
+    "MemoryNode",
+    "MemoryEntry",
+    "MemoryMetadata",
+    "MemoryScore",
+    "MemoryInputType",
+    "AgentProcessMode",
+    "TaskStatus",
+    "DeleteScope",
+    "QAPair",
+    "AddRequest",
+    "AddResponse",
+    "AsyncAddResponse",
+    "RecallRequest",
+    "RecallResponse",
+    "UpdateRequest",
+    "UpdateResponse",
+    "DeleteRequest",
+    "DeleteResponse",
+    "BatchDeleteRequest",
+    "BatchDeleteResponse",
+    "GetRequest",
+    "GetResponse",
+    "ListRequest",
+    "ListResponse",
+]

hy_memory-1.0.0/hy_memory/agent/__init__.py

@@ -0,0 +1,99 @@
+"""
+Agent Memory - 智能层 (Agent Layer)
+
+基于 LLM 的智能处理能力，提供语义理解、信息提取、推理判断等功能。
+该层是可选的，关闭后系统仍能正常工作。
+
+包含模块：
+- MemAgent: 智能体协调器，统一入口
+- Summarizer: Lite+Agent pipeline 摘要生成器 (L3_SUMMARY)
+- Abstractor: System 2 全量摘要智能体 (Session摘要/Schema归纳/Profile摘要)
+- Extractor: 提取智能体，提取结构化信息 (V2: 轻量提取/深度提取双模式)
+- Reflector: 反思智能体，检测冲突和更新 (V2: UpdateType分类/冲突检测/隐式推断)
+- EmotionAnalyzer: 情绪分析智能体，valence + arousal 双维标注
+- IntentionDetector: 意图检测智能体，前瞻性记忆 + 主动关怀
+- LLMProvider: LLM 提供器，统一的模型调用接口
+"""
+
+# Lite+Agent pipeline
+from .mem_agent import MemAgent, AgentResult, ProcessMode
+from .summarizer import Summarizer, SummaryResult
+from .extractor import Extractor, ExtractResult
+from .reflector import Reflector, ReflectResult, ConflictType, ConflictAction
+from .llm_provider import LLMProvider, LLMResponse, LLMConfig, LLMBackend
+
+# V2 Extractor
+from .extractor import ExtractMode, V2ExtractResult
+
+# System 2 / Pro Pipeline Abstractor
+from .abstractor import Abstractor, SessionSummaryResult, SchemaAbstractResult, ProfileSummaryResult
+
+# V2 Reflector
+from .reflector import (
+    V2ConflictType,
+    UpdateTypeResult,
+    ConflictDetectionResult,
+    ImplicitSignal,
+    ImplicitInferenceResult,
+)
+
+# V2 Emotion Analyzer
+from .emotion_analyzer import EmotionAnalyzer, EmotionAnalysisConfig, EmotionResult
+
+# V2 Intention Detector
+from .intention_detector import (
+    IntentionDetector,
+    IntentionDetectorConfig,
+    DetectedIntention,
+    IntentionDetectResult,
+    TriggeredIntentionItem,
+    IntentionTriggerResult,
+)
+
+__all__ = [
+    # MemAgent
+    "MemAgent",
+    "AgentResult",
+    "ProcessMode",
+    # Summarizer (Lite+Agent)
+    "Summarizer",
+    "SummaryResult",
+    # Abstractor (System 2)
+    "Abstractor",
+    "SessionSummaryResult",
+    "SchemaAbstractResult",
+    "ProfileSummaryResult",
+    # Extractor (V1)
+    "Extractor",
+    "ExtractResult",
+    # Extractor (V2)
+    "ExtractMode",
+    "V2ExtractResult",
+    # Reflector (V1)
+    "Reflector",
+    "ReflectResult",
+    "ConflictType",
+    "ConflictAction",
+    # Reflector (V2)
+    "V2ConflictType",
+    "UpdateTypeResult",
+    "ConflictDetectionResult",
+    "ImplicitSignal",
+    "ImplicitInferenceResult",
+    # Emotion Analyzer (V2)
+    "EmotionAnalyzer",
+    "EmotionAnalysisConfig",
+    "EmotionResult",
+    # Intention Detector (V2)
+    "IntentionDetector",
+    "IntentionDetectorConfig",
+    "DetectedIntention",
+    "IntentionDetectResult",
+    "TriggeredIntentionItem",
+    "IntentionTriggerResult",
+    # LLMProvider
+    "LLMProvider",
+    "LLMResponse",
+    "LLMConfig",
+    "LLMBackend",
+]