GraphMemory-IDE: AI-Powered Collaborative Memory Platform

GraphMemory-IDE

一款由 AI 辅助的 IDE 长期记忆系统，基于 LadybugDB 构建——这是一款嵌入式、列式、采用 MIT 许可证的图数据库。GraphMemory-IDE 是一个 MCP（Model Context Protocol）服务，提供语义向量搜索、基于图的知识存储和实时分析。它通过专用 IDE 插件与 VSCode、Cursor 和 Windsurf 集成。

图数据库： 后端运行在 LadybugDB 0.21.2 上，这是 KuzuDB 的积极开发继任者（KuzuDB 被 Apple 收购后，其开源开发已停止）。完整的迁移记录——包括经过验证的 API 差异、分阶段执行过程和操作迁移指南——请参见 MIGRATION_PLAN_LADYBUG.md 和 docs/migration/KUZU_TO_LADYBUG.md。

功能

• 基于图的记忆存储 — LadybugDB 嵌入式图数据库（Cypher / openCypher 方言），支持自动主键哈希索引和对所有列进行区域映射裁剪
• 语义向量搜索 — 使用 sentence-transformers 嵌入，在节点嵌入列上通过 array_cosine_similarity 执行 Top-K 查询
• Codon 加速图算法 — 可选通过 Codon 进行原生编译，在中心性、社区检测、路径分析和相似度计算方面实现 10-100 倍加速，并自动回退到 Python/NetworkX
• FastAPI 后端 — 异步 API，支持 JWT 身份验证（EdDSA/Ed25519）、可选只读模式、速率限制和安全中间件
• 实时分析 — 通过 WebSocket 和 SSE 流式传输，支持实时遥测仪表板
• Streamlit 仪表板 — 交互式可视化图指标、用户活动和系统健康状况
• 多 IDE 插件支持 — 提供适用于 VSCode、Cursor 和 Windsurf 的扩展
• 全面可观测性 — Prometheus 指标、Grafana 仪表板、健康检查和告警关联
• 生产就绪的 Docker 部署 — 多服务 Docker Compose，包含 Nginx、PostgreSQL、Redis 和监控栈

快速开始

Docker（推荐）

git clone https://github.com/elementalcollision/GraphMemory-IDE.git
cd GraphMemory-IDE/docker
docker compose up -d

服务将在以下地址提供：

• MCP 服务：http://localhost:8080/docs

本地开发

# 1. Install dependencies (Python 3.11+)
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# 2. Initialise the graph database schema (REQUIRED before first start —
#    the app opens the database but does not create the schema itself)
LADYBUG_DB_PATH=./data/ladybug.lbdb python server/init_db.py

# 3. Start the FastAPI server
uvicorn server.main:app --host 0.0.0.0 --port 8080 --reload

# 4. (optional) Start the Streamlit dashboard (separate terminal)
cd dashboard && streamlit run streamlit_app.py

配置

变量	默认值	描述
DB_LADYBUG_DB_PATH	./data/ladybug.lbdb	LadybugDB 图数据库文件的路径（单个 .lbdb 文件；父目录必须存在——应用会创建该文件）
DB_LADYBUG_READ_ONLY	false	以只读方式打开图数据库（数据库层会拒绝写入；跳过架构初始化）
JWT_SECRET_KEY	（自动生成）	用于签署 JWT 令牌的密钥；生产环境中请显式设置
DB_DATABASE_URL	postgresql://user:password@localhost:5432/graphmemory_dev	PostgreSQL 连接字符串（用于关系型数据和遥测数据存储）
DB_REDIS_URL	redis://localhost:6379/0	用于缓存的 Redis 连接（无法连接时会回退到内存缓存）
CODON_ENABLED	true	启用 Codon 加速
CODON_LIB_PATH	./codon/lib/	已编译 Codon 库的路径
CODON_MIN_GRAPH_SIZE	100	使用 Codon 路由所需的最小图规模

关于环境变量前缀的说明： 数据库相关设置由 pydantic 使用 DB_ 前缀读取——例如，设置 LADYBUG_DB_PATH 时应使用环境变量 DB_LADYBUG_DB_PATH。server/init_db.py 也支持不带前缀的 LADYBUG_DB_PATH 形式（并在一个发布周期内继续将 KUZU_DB_PATH 作为已弃用的回退选项）。

架构

GraphMemory-IDE 采用混合架构：I/O 密集型代码（FastAPI、数据库客户端、WebSocket）在 CPython 中运行，而计算密集型图算法可选择作为原生编译的 Codon 模块运行。

IDE Plugins (VSCode/Cursor/Windsurf)
        |
        v
  FastAPI Server (CPython)
   ├── JWT Auth (EdDSA) + Security Middleware (TrustedHost / rate limit)
   ├── MCP Protocol Handler
   ├── Telemetry Ingestion + Query (/telemetry/*)
   ├── Top-K Vector Search (/tools/topk)
   ├── Analytics Engine (/api/v1/analytics/*)
   └── Dashboard Routes + SSE (/dashboard/*)
        |
   ┌────┴─────────┐
   v              v
LadybugDB      PostgreSQL + Redis
(embedded      (relational store,
 graph DB,      sessions, cache)
 sync engine)
   |
   v
Codon Bridge (optional)
 ├── Graph Kernels (.so/.dylib)
 └── Python/NetworkX fallback

图数据库层（server/graph_database.py）：在进程内打开的嵌入式 LadybugDB 实例——无需单独的数据库服务。它提供线程安全的连接池（基于条件变量）、供异步处理程序使用的 LadybugDB 原生 AsyncConnection（GraphDatabaseManager.get_async_connection()）、架构管理（User / Project / Memory 节点表，以及 OWNS / COLLABORATES / CONTAINS / RELATES_TO / ACCESSED_BY 关系表）、支持参数化 Cypher 执行和 Prometheus 插桩的查询引擎，以及健康检查（通过 CALL show_tables() 验证架构完整性）。read_only 模式会以只读方式打开数据库，用于只读工作负载（例如分析副本）。

详细系统设计请参阅架构概览。

Codon 加速

codon/ 目录包含通过 Codon 编译为原生机器码的图算法实现。桥接层（codon/bridge/）会根据图的大小和库的可用性自动路由计算：

• 图内核：介数／接近／度中心性、PageRank、标签传播、Louvain 社区检测、BFS／Dijkstra 最短路径
• 数据处理：余弦相似度、批量向量运算、一致性哈希
• 回退：如果 Codon 库未编译，所有操作都会透明地回退到 NetworkX／numpy

使用以下命令编译 Codon 模块：

./scripts/build_codon.sh

API 概览

端点	方法	描述
/health	GET	系统健康状况（CPU／内存／磁盘检查）
/api/v1/status	GET	应用状态，包括 database.ladybug_path 和 read_only
/auth/token	POST	JWT 访问令牌（OAuth2 密码流）
/telemetry/ingest	POST	接收 IDE 遥测事件（经过验证的 EventType 枚举、ISO-8601 时间戳、JSON 序列化数据）
/telemetry/list	GET	列出遥测事件（分页）
/telemetry/query	GET	根据 event_type / user_id / session_id 筛选事件
/tools/topk	POST	Top-K 语义搜索：sentence-transformers 嵌入 + 对请求的节点表执行 array_cosine_similarity
/api/v1/analytics/*	GET	分析引擎（中心性、社区、聚类、流处理、GPU 状态）
/dashboard/*	GET	仪表板 API + SSE 实时流（/dashboard/stream/analytics）
/metrics	GET	Prometheus 指标

完整参考请参阅：API 指南。交互式文档位于 http://localhost:8080/docs（生产环境中禁用）。

项目结构

GraphMemory-IDE/
├── server/                # FastAPI backend
│   ├── main.py            # Application entry point
│   ├── core/              # Configuration and settings
│   ├── auth/              # SSO, MFA, onboarding
│   ├── auth_jwt.py        # JWT authentication
│   ├── analytics/         # Analytics engine
│   ├── collaboration/     # Real-time collaboration
│   ├── dashboard/         # Dashboard API routes
│   ├── monitoring/        # Health checks, metrics, alerting
│   ├── security/          # Security middleware
│   ├── streaming/         # WebSocket/SSE streaming
│   ├── backup/            # LadybugDB/PostgreSQL/Redis backup orchestration
│   ├── graph_database.py  # LadybugDB integration (pool, schema, query engine, health)
│   └── init_db.py         # Graph schema initialisation (run before first start)
├── dashboard/             # Streamlit UI
├── frontend/              # TypeScript/React frontend
├── codon/                 # Codon acceleration layer
│   ├── bridge/            # Python-Codon interop with fallback
│   ├── graph_kernels/     # Native graph algorithms (.codon)
│   └── data_processing/   # Native data operations (.codon)
├── docker/                # Docker Compose configs
│   ├── docker-compose.yml # Development environment
│   ├── docker-compose.test.yml # Test services (PostgreSQL + Redis, ephemeral)
│   └── production/        # Production multi-service setup
├── tests/                 # Test suites
│   ├── integration/       # Integration tests
│   ├── production/        # Production validation
│   ├── load_testing/      # Locust load tests
│   └── smoke/             # Smoke tests
├── docs/                  # Documentation (incl. docs/migration/)
├── ide-plugins/           # VSCode, Cursor, Windsurf extensions
├── monitoring/            # Prometheus & Grafana configs
├── scripts/               # Build, deployment, and test-DB scripts
└── kubernetes/            # Kubernetes manifests

测试

# Run all tests
PYTHONPATH=. pytest tests/ -v

# Run with coverage
PYTHONPATH=. pytest tests/ --cov=server --cov-report=html

# Run specific test categories
PYTHONPATH=. pytest tests/ -m unit
PYTHONPATH=. pytest tests/ -m integration
PYTHONPATH=. pytest tests/ -m "not slow"

已注册的测试标记：asyncio、unit、integration、slow、real_time、real_services、performance、mock_data、load、external、database、authentication（强制执行 --strict-markers）。

针对真实服务的集成测试

数据库集成测试需要 PostgreSQL 和 Redis 后端服务。临时测试配置会启动它们（Docker / OrbStack），与 fixture 默认值保持一致：

docker compose -f docker/docker-compose.test.yml up -d
python scripts/init_test_db.py          # create the app schema in the test DB
PYTHONPATH=. pytest tests/integration/test_database_integration.py -v
docker compose -f docker/docker-compose.test.yml down -v

如果没有这些服务，依赖 PG 的 fixtures 会正常跳过；由 LadybugDB 提供支持的测试会在进程内针对临时数据库运行，无需外部服务。

覆盖率目标：最低 85%。

生产部署

生产环境请使用多服务 Docker Compose 配置：

cd docker/production
cp env.production.template .env  # Configure environment variables
docker compose -f docker-compose.prod.yml up -d

这会启动 7 个以上的服务：Nginx（反向代理）、FastAPI、Streamlit、Analytics、PostgreSQL、Redis、Prometheus 和 Grafana，并配置隔离的网络子网和资源限制。还可使用 LadybugDB api-server sidecar（ghcr.io/ladybugdb/api-server）进行外部／管理图访问；生产环境中请固定版本标签。

完整的生产环境设置说明请参阅 Docker 部署指南。

迁移：Kuzu → LadybugDB

此代码库已从 Kuzu 0.10.0 迁移至 LadybugDB 0.21.2（2026-10）。扩展此集成时，请注意以下要点：

• Python API：import ladybug as lb；Connection(db) + init_connection()；采用 snake_case 的结果迭代方式（has_next() / get_next()，行是列表）
• 索引：仅支持 PK 哈希索引（自动创建）；0.21.2 不支持二级属性索引和 FULLTEXT 索引——区域映射用于满足筛选工作负载
• 向量搜索：使用 array_cosine_similarity（Kuzu 的 list_cosine_similarity 不存在）
• 存储：使用单个 .lbdb 文件；父目录必须已存在（与 Kuzu 不同，LadybugDB 不会创建该目录）
• CLI：lbug（brew install ladybug）；支持使用 EXPORT DATABASE / IMPORT DATABASE 迁移数据

完整且已验证的差异目录：MIGRATION_PLAN_LADYBUG.md §3。已部署实例的运维手册：docs/migration/KUZU_TO_LADYBUG.md。

文档

目录	描述
MIGRATION_PLAN_LADYBUG.md	Kuzu → LadybugDB 迁移：阶段、已验证的 API 差异、缺陷清单
docs/migration/	运维迁移指南 + 阶段验证脚本
docs/project/	项目概览、PRD、贡献指南、安全策略
docs/architecture/	系统架构、代码路径、网络流
docs/api/	API 参考和客户端示例
docs/deployment/	Docker、Kubernetes 和生产环境部署指南
docs/development/	开发者环境设置、代码质量、测试流程
docs/operations/	系统运维和性能调优
docs/monitoring/	Prometheus、Grafana 和告警配置
docs/analytics/	分析系统和 ML 组件
docs/ide-plugins/	VSCode、Cursor、Windsurf 插件开发
docs/user-guides/	教程和终端用户文档

贡献

有关开发工作流、提交规范和代码审查流程，请参阅贡献指南。

许可证

本项目采用 MIT License 授权。详情请参阅 LICENSE。