MemoryBase

MemoryBase 是一个面向 AI Agent 协作研发场景的文件—数据库双态长期记忆系统。

系统将 Markdown、会议纪要、讨论记录等人类可读文件导入数据库，切分为 SourceChunk，并进一步整理为可检索、可追溯、可权限控制、可审计、可版本化的 MemoryItem，最终导出为 Markdown Wiki。

项目定位

MemoryBase 不是普通聊天助手，也不是简单 RAG 知识库，而是一个以数据库为核心的长期记忆治理系统。

核心链路：

SourceDocument
  → SourceChunk
  → MemoryItem
  → MemoryEvidence
  → MemoryRevision / AuditLog
  → RecallLog / AccessPolicy
  → WikiPage / WikiPageRevision

技术栈

• Backend: FastAPI
• Frontend: React + Vite
• Database: PostgreSQL
• Graph Database: Neo4j（可选，用于知识图谱同步与可视化）
• Search: PostgreSQL Full Text Search（GIN tsvector / trigram）+ 可选 embedding 的 hybrid recall
• AI（可选）: OpenAI-compatible LLM 用于候选记忆抽取与 QA；本地 hashing embedding cache，未配置外部 provider 时透明 fallback 到 keyword
• CLI: mb / memorybase（sessions / observe / remember / search / recall）
• SQL: views, triggers, indexes
• Deployment: Docker Compose

功能模块

• Source 导入与 chunk 切分：SourceDocument / SourceChunk
• 记忆与证据链：MemoryItem / MemoryEvidence / MemoryRevision
• 治理与溯源：AuditLog、ConflictRecord 冲突治理、ForgetRequest 遗忘/归档审批、TimelineEntry
• 检索：lexical（FTS / trigram）+ 可选 embedding 的 hybrid recall（无 embedding 时透明 fallback 到 keyword），并投影为 Context Pack
• 权限与可见性：AccessPolicy、agent-aware visibility
• 候选记忆抽取：rule-based + 可选 LLM（结果写入 status='candidate'，需人工审批后进入 active）
• Wiki 投影：WikiPage / WikiPageRevision，可导出 Markdown
• Graph Explorer：PostgreSQL preview + 可选 Neo4j 同步的 provenance 图谱
• CLI / Agent Runtime：mb sessions / observe / remember / search / recall
• 评测：LoCoMo / LongMemEval / MemoryAgentBench adapters 与 evaluation framework
• 前端页面：Dashboard / Source / Memory / Recall / Governance / Wiki / Runtime / Graph

本地运行

docker compose up -d

cd backend
pip install -r requirements.txt
uvicorn app.main:app --reload

cd frontend
npm install
npm run dev

如果你只想跑 PostgreSQL，不需要同时启动 Neo4j：

docker compose up -d postgres

部署指南

1. 推荐方式：Docker 启动 PostgreSQL

如果你只想最快跑通数据库，直接在项目根目录执行：

docker compose up -d

这会启动项目自带的 PostgreSQL 服务，默认连接信息见 .env.example。

2. 一条命令安装大部分依赖

如果本机已经安装了 Python、Node.js 和 PostgreSQL，可以用下面的一条命令完成大部分依赖安装：

pip install -r backend/requirements.txt && cd frontend && npm install --include=dev

Windows PowerShell 下建议分两步执行，避免 shell 差异：

pip install -r backend/requirements.txt
Set-Location frontend
npm install --include=dev

3. 前后端启动

后端：

cd backend
uvicorn app.main:app --reload

前端：

cd frontend
npm run dev

4. 数据库初始化

数据库启动后，可以优先直接用仓库内置快捷命令：

npm run db:init
npm run db:seed
npm run db:check

常用命令说明：

• npm run db:init：执行 00_init.sql 到 06_triggers.sql
• npm run db:seed：执行 07_seed.sql 和 08_demo_queries.sql
• npm run db:reset：重建 public schema 后重新执行初始化和 seed
• npm run db:check：检查核心表与 demo 数据
• npm run db:setup：等价于 db:reset
• npm run db:run -- <sql-file>：读取 .env 后执行单个 SQL 文件，例如 npm run db:run -- database/04_indexes.sql

这些命令由跨平台的 python scripts/db_cli.py 统一驱动。 会优先读取当前终端的 DATABASE_URL，如果没设置，则自动读取项目根目录 .env，若 .env 不存在则回退读取 .env.example。

如果你暂时不想一次性执行完整流程，也可以按顺序执行单个 SQL 文件。推荐仍使用项目封装命令，这样会自动读取 .env：

npm run db:run -- database/00_init.sql
npm run db:run -- database/01_schema_core.sql
npm run db:run -- database/02_schema_memory.sql
npm run db:run -- database/03_schema_governance.sql
npm run db:run -- database/04_indexes.sql
npm run db:run -- database/05_views.sql
npm run db:run -- database/06_triggers.sql
npm run db:run -- database/07_seed.sql

如果直接使用裸 psql，PowerShell 不会自动读取 .env，需要你先在当前 shell 设置 DATABASE_URL。因此调试单个 SQL 文件时优先使用：

npm run db:run -- database/04_indexes.sql

如果使用快捷命令，确保本机 python 与 psql 都在 PATH 中，并在项目根目录执行：

npm run db:init

PostgreSQL 本机安装指南

1. 安装方式

如果不使用 Docker，可以直接在本机安装 PostgreSQL：

• Windows：下载安装官方安装器，安装 PostgreSQL 与 psql
• macOS：可用 Homebrew 安装
• Linux：可用系统包管理器安装

2. Windows 安装建议

安装完成后，建议：

• 记住超级用户密码
• 勾选命令行工具 psql
• 将 PostgreSQL 的 bin 目录加入系统 PATH

安装完成后可验证：

psql --version

3. 创建本地数据库

安装 PostgreSQL 后，创建项目数据库与用户：

CREATE USER memorybase WITH PASSWORD 'memorybase';
CREATE DATABASE memorybase_db OWNER memorybase;
GRANT ALL PRIVILEGES ON DATABASE memorybase_db TO memorybase;

4. 配置环境变量

.env.example 是示例模板，不会被程序自动当作运行配置读取。实际使用时，应该在项目根目录复制一份并命名为 .env：

cp .env.example .env

Windows PowerShell：

Copy-Item .env.example .env

然后再根据你自己的本机环境修改 .env。如果你本地 PostgreSQL 的用户名、密码、端口、数据库名和示例完全一致，可以直接使用；如果不一致，就需要修改 DATABASE_URL。

项目默认示例：

DATABASE_URL=postgresql://memorybase:memorybase@localhost:5432/memorybase_db
BACKEND_HOST=127.0.0.1
BACKEND_PORT=8000
FRONTEND_PORT=5173

如果要启用 Neo4j 图谱同步与 Graph Explorer：

NEO4J_ENABLED=true
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=memorybase
NEO4J_DATABASE=neo4j

docker compose up -d 会同时启动 PostgreSQL 和 Neo4j。Neo4j Browser 默认地址是 http://localhost:7474，后端图谱接口在 /api/graph/*，前端入口是 /graph。

图谱接口语义：

• GET /api/graph/workspace：agent-aware 视图，agent_id 可选
• 未传 agent_id：返回 human-friendly 视角，只包含 public/project memories
• 传 agent_id：按 v_agent_visible_memory 过滤，和 recall/search 的 agent 可见性一致
• GET /api/graph/workspace/preview：workspace 级预览图，不做 agent 可见性过滤
• POST /api/graph/workspace/sync：把 PostgreSQL 快照同步到 Neo4j，agent_id 仅用于 audit attribution，不改变同步内容

如果希望 Graph Explorer 展示更清晰的分层图谱示例，可以在完成基础 seed 后额外执行：

npm run db:run -- database/09_graph_demo.sql

然后在 /graph 页面点击 Use Graph Demo，再点击 Sync Neo4j。这个示例专门围绕“选题转向 → 架构决策 → 治理演示”组织，节点更少、层次更清楚。

Use Graph Demo 会切到图谱 demo workspace，并填入默认 demo agent；如果你清空 Agent ID 再加载图谱，则会回到 human-friendly 的 public/project 视角。

常见需要修改的地方：

• 用户名不是 memorybase
• 密码不是 memorybase
• PostgreSQL 端口不是 5432
• 数据库名不是 memorybase_db
• 后端或前端端口与你本机已有服务冲突

例如，如果你的本机 PostgreSQL 用户是 postgres，密码是 123456，数据库名是 memorybase，那么 .env 可以改成：

DATABASE_URL=postgresql://postgres:123456@localhost:5432/memorybase
BACKEND_HOST=127.0.0.1
BACKEND_PORT=8000
FRONTEND_PORT=5173

如果你使用 Docker Compose 启动仓库内自带的 PostgreSQL，并且没有改默认配置，那么通常可以直接沿用示例值，不需要改动。

5. 验证连接

psql postgresql://memorybase:memorybase@localhost:5432/memorybase_db -c "\dt"

或者直接使用：

npm run db:check

文档与材料

项目的设计文档、演示材料、源程序说明与参考资料统一放在 docs/ 目录下：

• 整合后的主报告：docs/final-report.md / docs/final-report.pdf
• 答辩 PPT：docs/final-assets/slides/final-defense.pdf
• 流程图 / ER / 时序图与系统演示截图：docs/final-assets/
• 需求 / 概念 / 逻辑 / 物理设计、范式、索引、API、分工等专项文档：见 docs/

完整的文档导览与主题索引见 docs/README.md；开发过程中的规划与记录归档在 docs/process/。

GitHub Workflows

• .github/workflows/ci.yml
  • push 到 main/dev 时执行主线持续集成
  • 包含基础文件检查、Python/Frontend 静态检查、后端 smoke test
• .github/workflows/pr-build-check.yml
  • pull_request 到 main/dev 时执行 PR 构建校验
  • 包含基础文件检查、静态检查、后端检查、前端构建
• .github/workflows/sql-check.yml
  • 针对 database/ 目录相关变更执行 PostgreSQL SQL 检查
  • 包含建库、建表、索引、视图、触发器加载与烟雾测试
• .github/workflows/pages.yml
  • main 分支触发 GitHub Pages 前端静态站点部署
• .github/workflows/codeql.yml
  • 可选安全扫描工作流
  • 对 Python 与 JavaScript 进行 CodeQL 分析

Demo 数据

• 原始讨论记录位于 data/raw_sources/demo_workspace/
• 可使用 scripts/import_demo_sources.py 列出当前 demo 源文件