Metadata-Version: 2.4
Name: memory-lake-sdk
Version: 0.3.0
Summary: 简化开发者对 Claude Memory Tool 使用的 Python SDK
Home-page: https://github.com/memorylake/memory-lake-sdk
Author: Memory Lake Team
Author-email: Memory Lake Team <team@memorylake.ai>
Maintainer-email: Memory Lake Team <team@memorylake.ai>
License: MIT License
        
        Copyright (c) 2025 Memory Lake Team
        
        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.
        
Project-URL: Homepage, https://github.com/memorylake/memory-lake-sdk
Project-URL: Documentation, https://github.com/memorylake/memory-lake-sdk/docs
Project-URL: Repository, https://github.com/memorylake/memory-lake-sdk
Project-URL: Bug Tracker, https://github.com/memorylake/memory-lake-sdk/issues
Project-URL: Changelog, https://github.com/memorylake/memory-lake-sdk/blob/main/CHANGELOG.md
Keywords: claude,anthropic,ai,memory,sdk,chatbot,conversation,context,python
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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 :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: anthropic>=0.39.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: flake8>=5.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: pre-commit>=2.20.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=5.0.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "docs"
Requires-Dist: myst-parser>=0.18.0; extra == "docs"
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: pytest-cov>=4.0.0; extra == "test"
Requires-Dist: pytest-mock>=3.8.0; extra == "test"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python



## 📦 安装

### 基础安装

```bash
pip install --extra-index-url https://test.pypi.org/simple/ memory-lake-sdk==0.3.0
```

### 开发安装

```bash
# 克隆仓库
git clone https://github.com/memorylake/memory-lake-sdk.git
cd memory-lake-sdk

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

### 测试安装

```bash
pip install -e .[test]
```

## 🚀 快速开始

### 环境变量配置

在使用 SDK 之前，您可以配置以下环境变量：

```bash
# 必需：API 密钥
export ANTHROPIC_API_KEY="sk-ant-********"

# 可选：指定模型（默认为 claude-4-sonnet）
export ANTHROPIC_MODEL="claude-sonnet-4-5"

# 可选：自定义 API 基础 URL（默认 https://api.anthropic.com）
export ANTHROPIC_BASE_URL="https://api.anthropic.com"
```

### 基础对话

```python
import os
from memory_lake_sdk import MemoryLakeClient

# 设置 API 密钥（也可以通过环境变量设置）
os.environ["ANTHROPIC_API_KEY"] = "xxx"

os.environ["ANTHROPIC_MODEL"] = "claude-sonnet-4-5-20250929"

os.environ["ANTHROPIC_BASE_URL"] = "xxx"
# 初始化客户端（会自动从环境变量读取配置）
client = MemoryLakeClient()

# 开始对话
response = client.chat("你好，请记住我喜欢喝咖啡")
print(response)

# Claude 会自动管理记忆，后续对话会记住这个信息
response2 = client.chat("我之前说过我喜欢什么？")
print(response2)  # 会提到咖啡
```

### 使用自定义配置

```python
from memory_lake_sdk import MemoryLakeClient

# 通过参数直接配置
client = MemoryLakeClient(
    api_key="your-api-key",
    model="claude-sonnet-4-5",  # 指定模型
    max_tokens=4096                     # 自定义令牌限制
)

response = client.chat("你好")
print(response)
```

### 手动记忆管理

```python   
from memory_lake_sdk import MemoryLakeClient        

client = MemoryLakeClient()

# 添加用户偏好
client.add_memory("/memories/preferences.xml", """
<user_preferences>
    <name>张三</name>
    <language>中文</language>
    <favorite_drink>咖啡</favorite_drink>
    <technical_level>中级</technical_level>
</user_preferences>
""")

# 查看记忆
preferences = client.get_memory("/memories/preferences.xml")
print(preferences)

# 在对话中使用记忆
response = client.chat("根据我的偏好，推荐一些适合我的学习资源")
print(response)
```

### 自定义存储后端

```python
from memory_lake_sdk import MemoryLakeClient, BaseMemoryBackend
import sqlite3

class DatabaseMemoryBackend(BaseMemoryBackend):
    def __init__(self, db_path: str):
        self.db_path = db_path
        self._init_database()

    def _init_database(self):
        # 初始化数据库表
        pass

    def view(self, path: str, view_range=None) -> str:
        # 实现查看功能
        pass

    def create(self, path: str, file_text: str) -> None:
        # 实现创建功能
        pass

    # 实现其他必需方法...

# 使用自定义后端
custom_backend = DatabaseMemoryBackend("./memory.db")
client = MemoryLakeClient(memory_backend=custom_backend)
```

## 📖 核心概念

### 记忆存储哲学

- **数据主权**: 记忆数据存储在用户环境中，SDK 不接触用户数据
- **责任分离**: SDK 提供处理记忆的能力，但不负责保管记忆本身
- **可插拔性**: 通过抽象接口支持多种存储方式

### 安全性

- **路径验证**: 所有路径必须以 `/memories` 开头
- **遍历防护**: 防止通过 `../` 等方式访问系统文件
- **权限控制**: 限制所有操作在指定基础目录内

## 🎯 API 参考

### MemoryLakeClient

SDK 的入口类，封装与 Claude API 和记忆工具的交互流程。

#### 初始化参数

| 参数 | 说明 |
| ---- | ---- |
| `api_key` | Anthropic API 密钥，默认读取 `ANTHROPIC_API_KEY` |
| `base_url` | API 基础 URL，默认读取 `ANTHROPIC_BASE_URL` |
| `memory_backend` | 自定义 `BaseMemoryBackend` 实例，默认文件系统后端 |
| `model` | 使用的模型名称，默认 `claude-4-sonnet` 或读取 `ANTHROPIC_MODEL` |
| `max_tokens` | 单次回复的最大 tokens 数，默认为 2048 |
| `context_management` | 上下文清理策略，默认为内置配置（保留记忆工具调用） |
| `memory_system_prompt` | 自定义记忆系统提示词 |
| `auto_save_memory` | 是否在工具调用后执行自动校验/持久化（默认开启） |
| `use_full_schema` | （已弃用）与旧版 SDK 兼容的参数，当前会被忽略 |
| `auto_handle_tool_calls` | 是否在收到 `tool_use` 时递归拉取更多消息（默认关闭） |

#### 对话与上下文

- `chat(user_input: str) -> str`
  - 发送用户输入，内部通过 `tool_runner` 调度记忆工具，并将 Claude 回复追加到历史中。
- `get_conversation_history() -> List[BetaMessageParam]`
  - 返回当前完整消息历史，可用于调试工具事件。
- `clear_conversation_history() -> None`
  - 清空会话历史记录（不会影响已写入的记忆文件）。
- `set_system_prompt(prompt: str) -> None`
  - 替换默认的记忆系统提示词。
- `set_context_management(config: Dict[str, Any]) -> None`
  - 自定义上下文清理策略，覆盖默认配置。
- `get_token_usage_info() -> Optional[Dict[str, Any]]`
  - 返回最近一次 API 调用的 token 统计（若 SDK 提供）。

#### 记忆管理

- `add_memory(path: str, content: str) -> None`
  - 创建或覆盖记忆文件，路径必须位于 `/memories` 下。
- `get_memory(path: str, view_range: Optional[tuple] = None) -> str`
  - 读取文件或目录内容，可选 `view_range=(start, end)` 限定行号。
- `delete_memory(path: str) -> None`
  - 删除指定文件或目录（根目录 `/memories` 会被保护）。
- `clear_all_memories() -> None`
  - 调用当前后端的清空逻辑，重置整个记忆目录。
- `memory_exists(path: str) -> bool`
  - 检查路径是否存在。
- `list_memories(path: str = "/memories") -> List[str]`
  - 返回指定目录下的文件/目录列表。
- `get_memory_stats() -> Dict[str, Any]`
  - 汇总当前记忆目录的文件数、目录数、容量等信息。
- `backup_memory(backup_path: str) -> None`
  - 导出记忆数据为 zip 包。
- `restore_memory(backup_path: str) -> None`
  - 从备份 zip 中恢复记忆。

#### 其他工具

- `interactive_loop() -> None`
  - 内置终端交互演示，支持常见命令。

> 提示：所有写操作都会触发 `auto_save_memory` 钩子，用于校验或扩展持久化策略。

### MemoryBackendTool

`MemoryBackendTool` 继承自官方 `BetaAbstractMemoryTool`，将任何 `BaseMemoryBackend` 实例包装成可注入 `tool_runner` 的工具。默认 `MemoryLakeClient` 会实例化该工具并将其传入 API 请求。自定义后端只需实现基类接口即可自动支持记忆工具调用。

### BaseMemoryBackend

抽象基类，约束所有记忆存储后端需实现的最小接口：

- `view(path, view_range=None)`：读取目录或文件（支持行号过滤）。
- `create(path, file_text)`：写入新文件，若父目录不存在需自动创建。
- `str_replace(path, old_str, new_str)`：在文件中进行唯一字符串替换。
- `insert(path, insert_line, insert_text)`：在指定行插入文本。
- `delete(path)`：删除文件或目录。
- `rename(old_path, new_path)`：移动/重命名路径。

可选扩展（如未实现将抛出 `NotImplementedError`）:

- `clear_all_memory()`、`memory_exists()`、`list_memories()`、`get_memory_stats()`、`backup_memory()`、`restore_memory()`。

### FileSystemMemoryBackend

默认实现，使用本地文件系统存储记忆数据，特点：

- 使用 `Path.resolve()` + `relative_to()` 防止目录遍历。
- 忽略隐藏文件，支持递归统计目录。
- `backup_memory` / `restore_memory` 使用 zip 归档便于迁移。
- 所有路径以 `/memories` 为根，自动创建缺失目录。

### 异常层级

- `MemorySDKError`：SDK 顶层异常基类。
- `MemoryBackendError` 及细分的 `MemoryPathError`、`MemoryFileOperationError`：后端相关错误。
- `MemoryAPIError` 及其子类：`MemoryAuthenticationError`、`MemoryRateLimitError`、`MemoryTimeoutError` 等，便于区分 API 失败原因。

开发时捕获这些异常，可以更精细地处理鉴权、限流、文件系统等错误情形。

## 🔧 配置选项

### 环境变量

- `ANTHROPIC_API_KEY`: Anthropic API 密钥（必需）
- `ANTHROPIC_MODEL`: 默认使用的 Claude 模型（可选，默认为 claude-4-sonnet）
- `ANTHROPIC_BASE_URL`: 自定义 API 基础 URL（可选，用于代理或私有部署）

### 上下文管理

SDK 支持自动上下文管理，当对话过长时自动清理旧的工具调用结果：

```python
client = MemoryLakeClient(
    context_management={
        "edits": [
            {
                "type": "clear_tool_uses_20250919",
                "trigger": {"type": "input_tokens", "value": 30000},
                "keep": {"type": "tool_uses", "value": 3},
                "exclude_tools": ["memory"],  # 保留记忆工具调用
            }
        ]
    }
)
```

## 🧪 测试

运行测试套件：

```bash
# 运行所有测试
pytest

# 运行测试并生成覆盖率报告
pytest --cov=memory_lake_sdk --cov-report=html

# 运行特定测试
pytest memory_lake_sdk/tests/test_client.py
```

## 📁 项目结构

```
memory_lake_sdk/
├── memory_lake_sdk/
│   ├── __init__.py          # 包初始化
│   ├── client.py            # 主客户端类
│   ├── memory_backend.py    # 记忆后端实现
│   └── exceptions.py        # 自定义异常
│
├── examples/                # 示例代码
│   ├── basic_chat.py        # 基础聊天示例
│   ├── manage_memory.py     # 记忆管理示例
│   └── custom_backend.py    # 自定义后端示例
│
├── tests/                   # 测试文件
│   ├── test_client.py       # 客户端测试
│   └── test_memory_backend.py # 后端测试
│
├── setup.py                 # 安装配置
├── pyproject.toml          # 项目配置
├── requirements.txt        # 依赖列表
└── README.md               # 项目文档
```

## 🚢 发布指南

1. 更新版本号：修改 `memory_lake_sdk/__version__` 并在 `CHANGELOG.md` 中记录变更。
2. 清理旧的构建产物：
   ```bash
   rm -rf build dist *.egg-info
   ```
3. 构建发布包：
   ```bash
   python -m build
   ```
4. 本地校验生成的包：
   ```bash
   twine check dist/*
   ```
5. 发布到 PyPI：
   ```bash
   twine upload dist/*
   ```

## 🤝 贡献指南

我们欢迎所有形式的贡献！

1. Fork 项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开 Pull Request

### 开发环境设置

```bash
# 克隆项目
git clone https://github.com/memorylake/memory-lake-sdk.git
cd memory-lake-sdk

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或
venv\Scripts\activate     # Windows

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

# 安装 pre-commit 钩子
pre-commit install
```

### 代码规范

- 使用 Black 进行代码格式化
- 使用 isort 进行导入排序
- 使用 flake8 进行代码检查
- 使用 mypy 进行类型检查

```bash
# 运行所有检查
black memory_lake_sdk/
isort memory_lake_sdk/
flake8 memory_lake_sdk/
mypy memory_lake_sdk/
```

## 📄 许可证

本项目采用 MIT 许可证。详见 [LICENSE](LICENSE) 文件。
