super-memory-kit 0.1.2

A Python CLI for managing standardized .memory workspaces.

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 标准结构

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

📦 安装方式

本地开发安装：

pip install -e .

安装后查看帮助：

mem --help

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

python -m super_memory.cli --help

开发时安装打包工具：

pip install -e .[dev]

后续普通安装方式：

pip install super-memory-kit

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

🛠 命令用法

初始化 .memory：

mem init

修复缺失结构：

mem fix

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

只读检查当前 .memory 状态：

mem status

删除 .memory：

mem remove

导出长期记忆到 long_term_export/：

mem long

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

mem insert ./long_term_export

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

查看帮助：

mem --help

🔧 最小使用示例

在一个新项目目录里：

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：

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 文件。若计划公开发布，建议补充明确许可证后再对外分发。