Metadata-Version: 2.4
Name: super-memory-kit
Version: 0.1.2
Summary: A Python CLI for managing standardized .memory workspaces.
Author: lemonmindyes
Project-URL: Homepage, https://github.com/lemonmindyes/super-memory-kit
Project-URL: Repository, https://github.com/lemonmindyes/super-memory-kit
Project-URL: Issues, https://github.com/lemonmindyes/super-memory-kit/issues
Keywords: cli,memory,ai,project-context
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: build>=1.2.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"

# super-memory-kit

🧠 `super-memory-kit` 是一个基于 Python 3.12+ 的命令行工具，用来管理项目中的 `.memory` 标准目录结构。

它聚焦一件事：让项目记忆有统一入口、清晰分层、低成本维护，方便 AI 协作、上下文整理和长期记忆复用。

## ✨ 项目简介

在实际协作中，项目记忆往往散落在不同文档里，不容易维护，也不方便复用。`super-memory-kit` 提供一套固定的 `.memory` 结构，并用 `mem` 命令完成初始化、修复、导出和替换。

当前已支持：

- `mem init`：初始化标准 `.memory`
- `mem fix`：补齐缺失结构
- `mem remove`：删除当前 `.memory`
- `mem long`：导出长期记忆
- `mem insert <path>`：替换长期记忆目录
- `mem status`：只读检查当前 `.memory` 状态

## 🚀 项目特点

- 标准化 `.memory` 目录结构，便于协作和迁移
- 使用 `src` 布局与 `pyproject.toml`，适合开发和发布
- 命令行接口简单直接，基于标准库 `argparse`
- CLI 输出包含命令名、状态和可操作提示，便于定位问题
- 长期记忆与当前项目记忆分层管理
- `cache.md` 专门用于低 token 快速读取

## 📁 `.memory` 标准结构

```text
.memory/
├─ memory.md
├─ rule.md
├─ long_term/
│  ├─ memory.md
│  ├─ cache.md
│  └─ archive.md
└─ current_project/
   ├─ memory.md
   ├─ cache.md
   └─ archive.md
```

## 📦 安装方式

本地开发安装：

```bash
pip install -e .
```

安装后查看帮助：

```bash
mem --help
```

如果当前终端还没有立即识别 `mem`，可以重新打开终端，或临时使用：

```bash
python -m super_memory.cli --help
```

开发时安装打包工具：

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

后续普通安装方式：

```bash
pip install super-memory-kit
```

PyPI 发布包名是 `super-memory-kit`。

## 🛠 命令用法

初始化 `.memory`：

```bash
mem init
```

修复缺失结构：

```bash
mem fix
```

`mem fix` 只会补齐缺失的标准 `.memory` 目录和文件，不会覆盖用户已有的 markdown 文件，也不会对旧模板文本做破坏性升级。如果想把旧模板文字升级到新写法，需要手动编辑对应文件，或等待未来单独的 `upgrade` 命令。

只读检查当前 `.memory` 状态：

```bash
mem status
```

删除 `.memory`：

```bash
mem remove
```

导出长期记忆到 `long_term_export/`：

```bash
mem long
```

用外部长期记忆目录替换当前项目的 `long_term/`：

```bash
mem insert ./long_term_export
```

`mem insert` 会在替换前保留当前 `.memory/long_term` 的备份策略，缺少必要文件或源目录不存在时会中止并给出提示。

查看帮助：

```bash
mem --help
```

## 🔧 最小使用示例

在一个新项目目录里：

```bash
mem init
mem status
mem fix
mem long
mem insert ./long_term_export
```

一个最常见的使用流程是：先用 `mem init` 建立标准结构，用 `mem status` 检查当前状态，再根据需要用 `mem fix` 补齐缺失项，用 `mem long` 导出长期记忆，最后通过 `mem insert` 在其他项目中复用。

当前版本暂时不做破坏性模板升级：`mem fix` 的职责是结构修复，不是内容迁移。已有 `.memory/*.md` 内容会被保留；缺失文件才会按当前默认模板创建。

CLI 在遇到权限、删除、复制、导出目录创建等文件系统问题时，会输出简洁错误和下一步建议。缺少 `.memory`、导入目录不完整等兼容性场景仍按原有报告式流程处理，不会破坏已有正常用法。

## 🧭 设计理念

- `memory.md` 是入口文件，负责说明整个 `.memory` 的读取顺序和用途
- `rule.md` 是规则文件，定义长期记忆、项目记忆、缓存更新与归档原则
- `long_term` 与 `current_project` 分层存放，分别承载稳定知识和当前项目上下文
- `cache.md` 用于低 token 快速读取，帮助在进入任务前先抓住最关键的信息

## 🔮 后续规划

- 支持更完整的导入导出形式，例如 zip 包
- 继续补充记忆写入与维护相关命令
- 优化跨项目复用体验

## 📚 开发与测试

当前项目使用标准库 `unittest`：

```bash
python -m unittest discover -s tests -t .
```

## 🚢 发布流程

- Pull Request 会触发 GitHub Actions CI。
- 合并到 `main` 后，先更新 `pyproject.toml` 中的版本号。
- 打 `vX.Y.Z` 格式的 tag，例如 `v0.1.0`。
- GitHub Actions 会构建包并自动发布到 PyPI。
- 项目使用 PyPI Trusted Publishing，不需要在仓库里保存 PyPI token。

## License

当前仓库中尚未提供单独的 `LICENSE` 文件。若计划公开发布，建议补充明确许可证后再对外分发。
