困境	表现	根源
上下文窗口天花板	对话越长，记忆越模糊，成本越高	依赖原始对话历史传递信息
"录音机式"记忆	仅能复述原文，无法理解关系与联想	向量检索只做语义匹配，缺乏结构
"不懂认错"的固执	错误信息无法修正，矛盾记录并存	记忆只有"写入"和"读取"，没有"更新"和"删除"

我们的答案：像人一样记忆

TrueHumanMEM 的设计哲学不是做一个更"精准"的记忆数据库，而是让 AI 具备以下四种人类记忆的本质特征：

选择性 —— 只记录有价值的关系，不记流水账。
模糊性 —— 能推断，也能坦诚地表达不确定性。
可塑性 —— 允许修正、覆盖旧记忆，认知随对话演化。
自明性 —— 能区分"用户陈述"与"模型推断"，记忆自知来源。

TrueHumanMEM 不是更强大的搜索引擎，而是更像人的记忆伙伴。

核心特性

🧠 最小化上下文窗口依赖

上下文仅用于协议适配，不承载对话记忆。

表面上，系统仍通过 messages 列表与 LLM API 交互——这是当前 Function Calling 接口的标准要求。但实际上：

不传递历史对话：每轮请求的 messages 仅包含系统提示、当前用户输入、上一轮的工具调用结果。
不累积轮次：过去的用户消息和助手回复不会被追加到后续请求中。模型无法通过翻看聊天记录来回忆信息。
记忆外置：所有需要跨轮次保留的事实、关系、偏好，全部写入 Neo4j 图数据库。当需要时，模型必须显式调用 memory_recall 工具，主动从图库中检索。

这种设计确保了：上下文长度不随对话轮次线性增长，记忆能力不囿于窗口上限。

🔗 结构化关系推理

以三元组 (主体, 关系, 客体) 存储事实，天然支持多跳路径查询。
即使信息未被用户直接陈述，系统也可通过路径组合进行推断。

✍️ 自主记忆决策

模型通过函数调用机制自主触发检索、写入或修正操作，避免硬编码管道。
基于对话语境判断"什么值得记"、"何时该查"。

🔄 完整的记忆生命周期管理

状态	含义	操作
active	当前有效记忆	写入时创建
deleted	软删除，逻辑失效	软删除操作
superseded	已被新关系替代	替代模式操作
archived	归档，低频访问	归档操作
物理删除	彻底清理	清理操作

🎯 置信度与来源标记

每条关系携带数值置信度，存储层区分"确凿"与"推测"。
表达层将不确定性转化为自然语言语气，实现从存储到表达的完整自知闭环。

🔒 隐私友好，数据可本地化

图库可部署于本地或私有环境，记忆数据由用户掌控。

🖥️ 现代化终端界面

基于 Textual 框架的 TUI 界面
实时消息显示与工具调用可视化
侧边栏配置与操作日志
跨平台支持（Windows/Linux/macOS）

架构设计

┌─────────────────────────────────────────────────────────────┐
│                        用户输入                              │
└─────────────────────────┬───────────────────────────────────┘
                            ▼
┌─────────────────────────────────────────────────────────────┐
│              LLM API (with Function Calling)                │
│  ┌───────────────────────────────────────────────────────┐  │
│  │              System Prompt: 记忆助手角色               │  │
│  │  + 当前用户输入 + 上一轮工具调用结果（极简上下文）      │  │
│  └───────────────────────────────────────────────────────┘  │
└─────────────────────────┬───────────────────────────────────┘
                            │ 模型自主决策调用工具
            ┌───────────────┼───────────────┬───────────────┐
            ▼               ▼               ▼               ▼
      ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌────────────┐
      │   recall   │  │   commit   │  │   purge    │  │ introspect │
      └─────┬──────┘  └─────┬──────┘  └─────┬──────┘  └─────┬──────┘
            │               │               │               │
            └───────────────┴───────┬───────┴───────────────┘
                                    ▼
                        ┌─────────────────────────┐
                        │      Neo4j 图数据库      │
                        │  (实体节点 + 关系边)     │
                        └─────────────────────────┘

轻量级上下文：每轮仅包含系统提示、上一轮工具调用结果、当前用户输入。过往对话历史不累积。
持续工具调用循环：模型可在一次回复中调用多个工具，直至给出最终文本回复。
可观测性支持：所有工具调用记录于会话日志，支持审计追踪与调试回溯。

快速开始

前置要求

Python 3.8+
Docker (用于 Neo4j 数据库)
DeepSeek API Key（或兼容 OpenAI 格式的任意 LLM API）

一键启动（推荐）

Windows

# 双击运行
start.bat

# 或命令行
python start.py

Linux / macOS

# Shell脚本
chmod +x start.sh
./start.sh

# 或Python
python3 start.py

启动脚本会自动：

✅ 启动 Docker (优先WSL，回退到Docker Desktop)
✅ 启动 Neo4j 数据库
✅ 创建虚拟环境
✅ 安装依赖
✅ 启动 TUI 应用

手动启动

1. 克隆仓库

git clone https://github.com/your-org/TrueHumanMEM.git
cd TrueHumanMEM

2. 安装依赖

pip install -r requirements.txt

3. 启动 Neo4j

# 使用Docker
docker run -d --name neo4j \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/graphmemory123 \
  neo4j:latest

4. 配置环境变量

export DEEPSEEK_API_KEY="your-api-key"
export NEO4J_URI="bolt://localhost:7687"
export NEO4J_USER="neo4j"
export NEO4J_PASSWORD="graphmemory123"

5. 运行应用

TUI 界面（推荐）

python -m graph_memory_tui.main

命令行 Demo

python graph_memory_demo.py

使用 TUI 界面

配置 API Key
- 按 F2 展开侧边栏
- 点击"配置"
- 输入你的 DeepSeek API Key
- 按 Enter 保存
开始对话
- 输入消息
- 按 Enter 发送
- 查看工具调用和AI响应
快捷键
- F1: 帮助
- F2: 切换侧边栏
- F3: 工具详情
- F5: 清屏
- F6: 退出

工具说明

系统向模型暴露 6 个记忆管理工具，由模型根据对话需求自主调用。

工具名	描述	关键参数
memory_recall	检索相关子图	query_intent (str): 关键词意图 seed_entities (List[str]): 起始实体 depth (int): 遍历深度 time_range (str, 可选): 时间范围
memory_commit	写入三元组	triplets (List[Dict]): 每项含 subject, relation, object, confidence (float, 0.0-1.0)
memory_purge	删除或替代记忆	criteria (Dict): 匹配条件 mode (str): soft / supersede new_relation (Dict, 可选): 替代关系
memory_introspect	查看当前会话元数据	session_id (str, 可选)
memory_archive	归档旧关系	days (int): 归档天数阈值
memory_cleanup	物理清理已删除数据	dry_run (bool): 预览模式

图数据库模式

节点（Entity）

属性	类型	描述
name	String	实体唯一标识
type	String	实体类型（模型动态提议）
created_at	DateTime	创建时间
updated_at	DateTime	最后更新时间
mention_count	Integer	被提及次数

关系（RELATES）

属性	类型	描述
type	String	关系类型
created_at	DateTime	关系创建时间
session_id	String	所属会话 ID
turn_id	Integer	会话内轮次编号
status	String	active / deleted / superseded / archived
confidence	Float	置信度 0.0 ~ 1.0
date_bucket	String	日期分桶 (YYYY-MM-DD)
supersedes	Integer	（可选）指向替代关系 ID

索引与约束：实体名与会话 ID 唯一约束；关系属性建立索引以确保查询性能。

与传统方案的对比

维度	传统上下文窗口	向量 RAG	TrueHumanMEM
记忆跨度	受窗口长度限制	检索精度随数据量下降	跨会话持久化，图结构保证精度
关系推理	依赖模型上下文推理	仅语义相似匹配	原生多跳路径查询
记忆修正	只能追加新消息	旧向量无法更新	完整状态机（软删除、替代）
不确定性表达	无	无	置信度 + 语气标记
数据主权	全部上传 API	向量库常为云端	图库可本地化部署
可解释性	黑盒	难以解释召回原因	显式关系路径，可审计

路线图

Phase 1: 核心稳定（当前）

核心六工具 + Neo4j 集成
函数调用驱动自主决策
软删除与替代模式
TUI 界面
一键启动脚本
多语言支持

Phase 2: 体验优化

来源标记增强：存储层显式区分"用户陈述"与"模型推断"
端侧轻量化：适配轻量级图存储，支持资源受限环境
全文索引优化：提升大规模数据检索性能
人工干预接口：支持显式记忆编辑与强制检索指令

Phase 3: 能力扩展

多模态记忆：支持非文本记忆关联
可视化界面：图形化展示个人知识图谱
流式输出：实时显示AI响应

限制与注意事项

事实准确性依赖底层模型能力：系统通过 LLM 进行关系抽取与推断，可能产生错误事实，建议关键信息人工复核。
函数调用能力依赖：模型需支持稳定的 function calling 接口，不同 LLM 表现可能存在差异。
性能基准待补充：当前版本未针对超大规模图谱（千万级节点）进行优化，极端场景下查询延迟可能上升。
隐私边界：本地部署仅保证数据存储位置可控，LLM API 调用仍受服务商条款约束。

文档

详细文档请查看 docs/ 目录：

贡献

欢迎任何形式的贡献！请先阅读贡献指南。

许可证

本项目采用 MIT License。

TrueHumanMEM —— 让 AI 的记忆方式，更像人。

Languages

Python 63.5%

HTML 33.5%

Shell 1.6%

CSS 0.8%

C++ 0.3%

Other 0.3%

README.md Unescape Escape

TrueHumanMEM - Graph Memory TUI

📖 目录

背景与理念

传统 AI 记忆的三大困境