# xingyao-memory-core

**Repository Path**: feng-chenhao/xingyao-memory-core

## Basic Information

- **Project Name**: xingyao-memory-core
- **Description**: 记忆芯skill，用来同步不同agent的记忆，绘制项目图谱，达到节省token的效果
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-07-04
- **Last Updated**: 2026-10-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 记忆芯 (memory-core) v3.2.0

> 跨 Agent 项目记忆中枢 —— 本地离线运行，知识图谱 + 项目文件图谱 + 项目状态 + 会话记忆 + 全自动画像与纠错记忆。
> 所有记忆数据只存公共记忆目录 `~/.memory-core`，绝不写入项目目录。

## 核心能力

- **项目自动识别**：从任意子目录自动向上定位项目根；同一项目无论哪个 Agent、哪个目录进入，都自动共享同一 workspace 和同一份项目图谱（映射持久化在公共记忆目录）。
- **知识图谱记忆**：学习一次，永久记住，SimHash 语义匹配，自动建边；边按节点稳定 uid 持久化，多 Agent 并发演化不错位。
- **项目文件图谱**：按项目分文件存储于 `~/.memory-core/data/project_graphs/`，`session`/`learn`/`query`/`search`/`auto` 自动检查新鲜度并后台异步扫描，不阻塞对话。
- **项目状态上下文**：沉淀决策、待办、未决问题、变更、里程碑。
- **会话记忆**：自动总结会话，跨 Agent 共享上下文。
- **全局用户画像**：调用自动入口时记录显性偏好和轻量风格统计，注入摘要不超过 200 字。
- **踩坑纠错记忆**：用户指出错误时自动沉淀，后续相关话题自动注入预警。
- **Token 节省账本**：记录自动管线的全量基准、实际注入和节省估算。
- **待确认队列**：核心信息直接入库，不确定信息先暂存待确认。
- **推理工具**：智能纠错、数据分析、文章总结、因果链提取、关联推荐。

## 授权模式

记忆芯 v3.2.0 为商业软件，采用本地离线 License：

- **读操作永久开放**：即使 license 过期，查询、搜索、统计等读操作仍可继续使用。
- **写操作需有效 license**：学习新知识、更新项目图谱、修改项目状态等操作需有效 license。
- **首次激活自动绑定机器**：license 首次激活时写入当前机器指纹，之后在该机器可离线使用。
- **离线激活**：通过开发者提供的 `license.json` 文件激活，无需联网。

```cmd
memory-core.exe license --file license.json
```

## 下载与安装

### 无 Python 环境（推荐终端用户）

1. 下载对应平台发布包：
   - Windows：`memory-core-v3.2.0-win.zip`
2. 解压到任意目录。
3. 运行安装命令：
   ```cmd
   memory-core.exe install
   ```
4. 按提示选择 Agent、skills 目录和记忆保存路径。
5. 安装完成后，向开发者申请 license 并激活即可使用完整功能。

### 有 Python 环境（开发者）

```bash
python -m pip install .
memory-core --help
```

## 快速开始

```bash
# 启动会话，后台自动更新项目图谱
memory-core session

# 一句话自动入口：画像、意图识别、检索、纠错、token 账本自动处理
memory-core auto "我喜欢先给结论，再给必要细节"
memory-core auto "错了，认证 token 不能放 query"

# 学习知识
memory-core learn "项目使用 FastAPI 框架"

# 查询
memory-core query FastAPI

# 项目图谱（后台异步执行）
memory-core project_graph create
memory-core project_graph status

# 查看 license 状态
memory-core license --status
```

## 命令总览

| 命令 | 说明 |
|---|---|
| `session` | 启动会话并刷新注入文件 |
| `auto` | 自然语言自动入口 |
| `learn` | 从内容学习知识 |
| `query` | 查询知识节点 |
| `search` | 图扩散搜索 |
| `project_graph` | 创建/更新/查看项目图谱（后台异步） |
| `project_search` | 项目图谱关键词搜索 |
| `decision` / `action` / `question` | 项目决策 / 待办 / 未决问题 |
| `status` | 查看项目状态 |
| `stats` / `selfcheck` | 统计信息 / 自检 |
| `pending` / `confirm` / `ignore` | 待确认队列管理 |
| `backup` / `restore` | 数据备份与恢复 |
| `export` / `import_kg` | 数据导出与导入 |
| `license` | license 激活与状态查询 |

完整命令与 Agent 使用方式请参考 `SKILL.md`。

## 多 Agent 共享

每个 Agent 只需执行一次安装，所有 Agent 共享同一个记忆根目录（默认 `~/.memory-core`）。

安装时支持一次安装到多个 Agent：

```text
Agent: zcode codex
```

## 项目结构

```
.
├── cli.py                      # CLI 入口
├── engine.py                   # 核心记忆引擎
├── project_identity.py         # 项目身份识别（项目根/workspace 映射/图谱路径）
├── project_graph.py            # 项目文件图谱
├── project_context.py          # 项目状态上下文
├── session_memory.py           # 会话记忆
├── pending_queue.py            # 待确认队列
├── user_profile.py             # 全局用户画像
├── intent_detector.py          # 自然语言意图识别
├── pitfall_memory.py           # 踩坑纠错记忆
├── token_ledger.py             # Token 节省账本
├── config.py                   # 全局配置
├── license_manager.py          # License 管理
├── license_keys.py             # RSA 密钥材料
├── rsa_utils.py                # 纯 Python RSA 工具
├── license_core.pyx            # Cython 校验核心
├── graph_worker.py             # 后台图谱扫描工作进程
├── install.py                  # 安装脚本
├── build_package.py            # 兼容入口，实际实现位于 tools/
├── generate_license.py         # 兼容入口，实际实现位于 tools/
├── tools/                      # 开发、构建、license 签发工具
├── packaging/                  # PyInstaller、Cython 与发布批处理配置
├── tests/                      # 测试套件
└── docs/                       # 设计文档
```

## 测试

```bash
python -m pytest tests -q
```

## 安全与隐私

- **零外部运行时依赖**：核心逻辑仅使用 Python 标准库。
- **本地存储**：所有记忆数据保存在用户指定的本地目录，不上传云端。
- **无自动更新**：本产品不会自动联网下载或更新任何文件，避免用户感知到不安全的后台行为。
- **License 离线校验**：采用 RSA-SHA256-PKCS#1v1.5 本地签名校验，私钥不随二进制分发，激活过程无需联网。
- **可选 Cython 加固**：构建时若安装 Cython 与 C 编译器，会自动编译 `license_core` 为 C 扩展，提高校验逻辑篡改门槛；未安装时自动回退到纯 Python。

## 许可

Proprietary — 商业软件，未经授权不得分发或用于商业用途。

## CLI 注意事项

- `--memory-root` 是全局参数，支持放在子命令前或子命令后；推荐写在子命令前，例如：
  `memory-core --memory-root D:\memory-core-data license --status`
- Windows 终端如果出现中文乱码，请使用 UTF-8 终端，或先执行：
  `chcp 65001`
  PowerShell 自动化脚本可设置：
  `$env:PYTHONIOENCODING = "utf-8"`