memectl 0.2.0

A centralized, tiered memory system with knowledge graph for AI assistants

Meme — 中心化记忆系统

一个基于知识图谱的个人记忆管理系统，为 AI 助手提供持久化、分层、可检索的记忆能力。

特性

• 三层记忆模型：Working（每次加载）→ Archive（图遍历检索）→ Cold（BM25 搜索可命中，可回温）
• 知识图谱：记忆之间通过 [[link]] 互相引用，支持 BFS 图遍历检索
• 重要性衰减：长期未访问的记忆自动降级，频繁使用的自动升级
• 错误纠正：记住 CLI 命令变更等操作性纠错，避免重复犯错
• 知识摄入：从 URL、文档、会话中学习并内化为记忆
• 加密保险库：敏感记忆通过 macOS Keychain + AES-256 加密存储
• Obsidian 兼容：.md 文件可直接在 Obsidian 中打开，图谱视图自动生效
• Claude Code 集成：通过 hooks 自动注入记忆上下文

安装

前置要求

• Python 3.12+
• macOS / Linux

方式 1：一键安装（推荐）

curl -sSL https://raw.githubusercontent.com/hyooeewee/Meme/main/install.sh | bash

自动处理 uv 安装、仓库克隆、PATH 配置。

方式 2：uvx / pipx

# uv（推荐）
uvx memectl install

# pipx
pipx run memectl install

方式 3：从源码安装（开发）

git clone https://github.com/hyooeewee/Meme.git
cd Meme
uv run ./meme setup

安装选项

# 基础安装
meme setup

# 安装 + 从现有 Claude Code 记忆迁移
meme setup --migrate

验证

meme version
meme doctor

快速开始

# 添加记忆
meme add "使用 uv 管理 Python 依赖，不使用 pip" --type feedback --importance 0.8

# 搜索记忆
meme search "python 依赖"

# 列出所有记忆
meme list

# 按层级列出
meme list --tier working

# 图遍历检索（从某个记忆出发，沿关联扩展）
meme query mem_xxx

# 从 URL 学习
meme learn https://docs.example.com/guide

# 从本地文件学习
meme learn --file ./notes.md

命令参考

记忆管理

命令	说明
meme add "内容" [选项]	添加新记忆
meme list [选项]	列出记忆
meme search "关键词"	BM25 关键词搜索
meme query mem_id	图遍历检索（核心命令）
meme edit mem_id	编辑记忆内容和元数据
meme delete mem_id	删除记忆
meme forget mem_id [选项]	遗忘记忆（软/硬/彻底）

add 选项：

• --type TYPE — 类型：feedback / project / user / reference / knowledge / correction
• --importance N — 重要性 0.0~1.0（默认 0.5）
• --tags TAG1,TAG2 — 标签
• --links mem_a,mem_b — 关联记忆
• --sensitive — 加密存储到 vault

list 选项：

• --tier TIER — 按层级过滤：working / archive / cold
• --tag TAG — 按标签过滤
• --sort ORDER — 排序：importance / recent / heat

forget 选项：

• --hard — 从文件系统彻底删除
• --hard --purge — 彻底删除 + 清理 git history

学习与摄入

命令	说明
meme learn <url>	从 URL 抓取内容，提炼为记忆
meme learn --file <path>	从本地文件提取，提炼为记忆

生命周期

命令	说明
meme decay [--dry-run]	执行重要性衰减扫描
meme promote mem_id	手动提升到 working 层
meme demote mem_id	手动降级
meme warm mem_id	将 cold 记忆回温到 archive
meme link mem_a mem_b	创建记忆关联
meme suggest-links	基于使用模式建议新关联
meme heat	显示当前会话热度

迁移

命令	说明
meme import --from claude	从 Claude Code 项目记忆迁移
meme import --from claude-global	从 Claude Code 全局配置迁移
meme import --from codex [--path]	从 Codex 迁移
meme sync --incremental	增量同步（检测源文件变化）

维护

命令	说明
meme doctor [--fix]	健康检查 + 自动修复
meme backup	手动备份
meme gc	清理旧备份
meme reindex	重建 index.json + graph.json
meme stats	统计信息
meme export [--format json|md]	导出所有记忆

系统

命令	说明
meme version	显示当前版本 + 检测最新版本
meme upgrade [--check] [--force]	自我升级
meme changelog	查看版本变更历史
meme uninstall [--keep-data]	卸载 Meme

记忆类型

类型	用途	默认重要性
feedback	用户对 AI 行为的纠正和偏好	0.6
project	项目相关的上下文和状态	0.5
user	用户身份、背景、偏好	0.8
reference	外部资源的指针和摘要	0.4
knowledge	从文档/URL 学习的知识	0.5
correction	CLI 命令变更等操作性纠错	0.9

三层记忆模型

┌─────────────────────────────────────────────────┐
│  Working (importance >= 0.8)                     │
│  每次会话自动加载，token 预算 2000               │
├─────────────────────────────────────────────────┤
│  Archive (0.2 <= importance < 0.8)               │
│  图遍历检索时按距离衰减加载                      │
│  load_weight = importance × (0.4 ^ distance)     │
├─────────────────────────────────────────────────┤
│  Cold (importance < 0.2)                         │
│  BM25 搜索可命中，连续 3 次命中自动回温          │
└─────────────────────────────────────────────────┘

图遍历检索

查询命中一个记忆节点时，沿知识图谱 BFS 扩展：

查询 "docker 权限问题"
  │
  ├─ 命中: feedback_docker_permission.md (distance: 0) → 全量加载
  │
  ├─ 1 级连接 (distance: 1) → 加载摘要
  │   ├─ install_permission.md
  │   └─ project_ecoctrl.md
  │
  └─ 2 级连接 (distance: 2) → 仅标签
      └─ knowledge_docker.md

Obsidian 兼容

记忆文件为标准 .md 格式，支持 Obsidian 的 [[wiki-link]] 语法。直接在 Obsidian 中打开 ~/.meme/ 目录即可使用图谱视图和反向链接。

Claude Code 集成

meme setup 自动注册三个 hooks：

Hook	触发时机	行为
SessionStart	会话开始	加载 working 记忆 + 纠正记忆
UserPromptSubmit	用户输入	关键词搜索 → 图遍历 → 注入相关记忆
SessionEnd	会话结束	写回 access_count，自动升降级

加密保险库

敏感记忆（API key、密码等）使用 macOS Keychain + AES-256 加密：

# 添加加密记忆
meme add "API key: sk-xxx" --sensitive --type knowledge

# 搜索时只显示摘要，解密需要 Keychain 授权
meme search "api key"

卸载

# 卸载但保留数据
meme uninstall --keep-data

# 完全卸载
meme uninstall

许可证

MIT