使用说明

MemoryGraph

Graph-based Memory CLI for AI Coding Agents

A graph-based memory system that gives AI coding agents persistent memory.
Store patterns, track relationships, retrieve knowledge across sessions.

与编码代理一起使用

编码代理已经执行shell命令，因此它们可以直接使用MemoryGraph。两个步骤：全局安装，然后添加说明。

安装

cd memory-graph/ts && bun install && bun link
# or: bun build src/cli.ts --compile --outfile ~/.local/bin/memorygraph
memorygraph stats  # verify

memorygraph 现在可以从任何目录访问。数据持续存在 ~/.memorygraph/.

添加代理说明

将此粘贴到代理的指令文件中(~/.claude/CLAUDE.md, .cursorrules, .windsurfrules，或 AGENTS.md):

## Memory
`memorygraph` CLI is installed. Use it for persistent memory across sessions.

Before work: `memorygraph recall --query "<task>" --limit 10` and `memorygraph briefing`
On decisions/fixes: `memorygraph store --type solution --title "<title>" --content "<what>" --tags "<component>,fix"`
On errors: `memorygraph store --type error --title "<error>" --content "<details>" --tags "<component>,error"`
Link: `memorygraph link <from-id> <to-id> SOLVES --strength 0.8`
Session end: `memorygraph store --type conversation --title "Session: <topic>" --content "<summary>" --tags "<tags>"`
Types: solution | problem | code_pattern | fix | error | workflow | command | technology
Tags: lowercase, hyphenated, include component (auth, database, cli), 2-5 per memory
Do NOT wait to be asked. Store automatically on triggers.

示例会话

# Start: load context
memorygraph recall --query "authentication redis" --limit 10
memorygraph briefing

# Fix a bug: store problem + solution, link them
memorygraph store --type problem --title "Auth token expiry too short" --content "Tokens expiring after 1h" --tags "auth,bug"
# → abc-123
memorygraph store --type solution --title "Extend token expiry to 24h" --content "Changed JWT expiry, added refresh rotation" --tags "auth,fix" --importance 0.8
# → def-456
memorygraph link def-456 abc-123 SOLVES --strength 0.9

# End: store summary
memorygraph store --type conversation --title "Session: auth token fix" --content "Fixed token expiry, added refresh rotation" --tags "auth,session-summary"

多项目设置

所有项目共享 ~/.memorygraph/falkordblite.db 默认情况下。要隔离每个项目，请执行以下操作：

export MEMORY_FALKORDBLITE_PATH=~/.memorygraph/my-project.falkor
# or tag memories with project name and filter:
memorygraph search --query "auth" --tags my-project

故障排除

代理未使用命令：在说明中使用“必需”/“必须”，包括确切的命令
未找到命令: bun link 从 ts/，或确保 ~/.local/bin 在PATH上
记忆无法持久: memorygraph config 为了检查路径， memorygraph health 验证

为什么选择MemoryGraph？

图形关系带来差异

平面存储（CLAUDE.md，矢量存储）将内存作为独立的条目保存。图形存储将它们连接起来：

[timeout_fix] --CAUSES--> [memory_leak] --SOLVED_BY--> [connection_pooling]
     |                                                        |
     +------------------SUPERSEDED_BY------------------------+

问题：“重试逻辑发生了什么？”返回完整的因果链，而不仅仅是单个记忆。

何时使用What

使用CLAUDE.md/AGENTS.md	使用MemoryGraph
“始终使用2-space缩进”	“上次我们使用4-space时，它打破了门楣”
“提交前运行测试”	“由于X，身份验证测试失败，由Y修复”
静态规则、基本指令	具有关系的动态学习

CLI命令

内存操作

命令	目的	示例
`store`	存储新内存	`store --type solution --title "Fix" --content "..." --tags redis,fix`
`get`	按ID获取内存	`get <memory-id>`
`update`	更新现有内存	`update <id> --title "New title"`
`delete`	删除内存	`delete <memory-id>`
`search`	使用筛选器搜索	`search --query "timeout" --tags redis --limit 10`
`recall`	自然语言回忆	`recall --query "authentication security"`
`related`	获取相关回忆	`related <id> --types SOLVES,CAUSES --max-depth 2`
`link`	建立关系	`link <from-id> <to-id> SOLVES --strength 0.8`

上下文搜索

命令	目的
`context-search`	按类型、强度或上下文文本搜索关系
`contextual-search`	在内存的相关项目中搜索

智能

命令	目的
`entities`	从内存中提取实体（文件、函数、类、技术）
`patterns`	找出类似的问题并提出模式建议
`context`	通过实体和关键字匹配实现智能上下文检索

分析

命令	目的
`stats`	数据库统计信息（内存计数、类型、关系）
`activity`	最近的活动总结中存在未解决的问题
`visualize`	图形可视化数据（节点和边）
`similarity`	分析给定内存的解决方案相似性
`learning`	为某个主题推荐学习路径
`gaps`	识别知识差距（未解决的问题、缺失的联系）

主动的

命令	目的
`briefing`	生成一份包含最近活动和未决问题的会议简报
`predict`	根据当前情况预测可能需要什么
`warn`	警告潜在问题（已弃用的方法、已知错误）
`outcome`	记录记忆结果（成功/失败跟踪）

整合

命令	目的
`capture`	从当前环境中捕获任务上下文
`analyze-project`	分析当前项目代码库
`workflow`	跟踪或建议工作流程改进

时间的

命令	目的
`as-of`	查询特定时间存在的关系
`history`	获取完整的关系历史记录以供记忆
`changes`	显示自时间戳以来的关系变化

数据管理

命令	目的
`export`	导出为JSON或Markdown
`import`	从JSON导入
`migrate`	在后端之间迁移
`health`	进行健康检查
`config`	显示当前配置

后端

后端	类型	配置	本机图	零配置	最适合
falkordblite （默认）	嵌入式	文件路径	密码	是	默认，无服务器的图形查询
SQLite	嵌入式	文件路径	模拟	是	零依赖回退
壁纸	客户端服务器	主机：端口	Cypher	否	高性能生产
内存图	客户端服务器	Bolt URI	Cypher	否	实时分析
云	云	API密钥	Cypher	否	多设备同步，团队共享

后端配置

# Use FalkorDBLite (default, zero-config)
bun run src/cli.ts stats

# Use SQLite
MEMORY_BACKEND=sqlite bun run src/cli.ts stats

# Use FalkorDB (client-server)
MEMORY_BACKEND=falkordb MEMORY_FALKORDB_HOST=localhost MEMORY_FALKORDB_PORT=6379 bun run src/cli.ts stats

# Use Memgraph
MEMORY_BACKEND=memgraph MEMORY_MEMGRAPH_URI=bolt://localhost:7687 bun run src/cli.ts stats

# Use Cloud
MEMORY_BACKEND=cloud MEMORYGRAPH_API_KEY=mg_your_key bun run src/cli.ts stats

环境变量

变量	描述	默认值
`MEMORY_BACKEND`	后端类型	`falkordblite`
`MEMORY_FALKORDBLITE_PATH`	FalkorDBLite数据库路径	`~/.memorygraph/falkordblite.db`
`MEMORY_SQLITE_PATH`	SQLite数据库路径	`~/.memorygraph/memory.db`
`MEMORY_FALKORDB_HOST`	FalkorDB服务器主机	`localhost`
`MEMORY_FALKORDB_PORT`	FalkorDB服务器端口	`6379`
`MEMORY_MEMGRAPH_URI`	Memgraph螺栓URI	`bolt://localhost:7687`
`MEMORYGRAPH_API_KEY`	云API密钥	-
`MEMORYGRAPH_API_URL`	云API URL	`https://graph-api.memorygraph.dev`
`MEMORY_TOOL_PROFILE`	刀具轮廓（核心或延伸）	`core`
`MEMORY_LOG_LEVEL`	日志级别	`INFO`

内存类型

类型	用例
`task`	任务和行动项
`code_pattern`	重复出现的代码模式或约定
`problem`	遇到的问题或挑战
`solution`	选择的解决方案、决策或方法
`project`	项目背景、环境、设置信息
`technology`	技术选择和评估
`error`	发现错误
`fix`	应用于错误的修复
`command`	有用的命令或CLI代码片段
`file_context`	特定文件的上下文
`workflow`	工作流或流程描述
`general`	通用存储器
`conversation`	对话摘要

关系类型

类型	含义
`RELATED_TO`	一般连接
`BUILDS_ON`	新内存扩展旧内存
`CONTRADICTS`	新内存取代或使旧内存无效
`CONFIRMS`	新记忆为旧记忆提供了证据
`SOLVES`	解决方案解决问题
`CAUSES`	一个记忆引发另一个记忆
`REQUIRES`	一个记忆依赖于另一个记忆
`IMPROVES`	对现有方法的改进
`REPLACES`	取代旧方法
`DEPENDS_ON`	工作流依赖关系

内存最佳实践

会话工作流

# Start of session: recall recent context
bun run src/cli.ts recall --query "recent work" --limit 10

# During work: store decisions and patterns
bun run src/cli.ts store \
  --type solution \
  --title "Use JWT for auth" \
  --content "JWT tokens with 24h expiry, refresh token rotation" \
  --tags "auth,security,api" \
  --importance 0.8

# Link it to a prior decision
bun run src/cli.ts link <new-id> <prior-id> BUILDS_ON --strength 0.9

# End of session: store summary
bun run src/cli.ts store \
  --type conversation \
  --title "Session: auth refactor" \
  --content "Refactored auth middleware, added JWT, fixed token refresh bug" \
  --tags "auth,session-summary"

# Export backup
bun run src/cli.ts export --format json --output session-backup.json

添加到CLAUDE.md或AGENTS.md

## Memory Protocol

### REQUIRED: Before Starting Work
You MUST use `recall` before any task. Query by project, tech, or task type.

### REQUIRED: Automatic Storage Triggers
Store memories on ANY of:
- Git commit: what was fixed/added
- Bug fix: problem + solution
- Architecture decision: choice + rationale
- Pattern discovered: reusable approach

### Memory Fields
- Type: solution | problem | code_pattern | fix | error | workflow
- Title: Specific, searchable
- Content: Accomplishment, decisions, patterns
- Tags: project, tech, category (required)
- Importance: 0.8+ critical, 0.5-0.7 standard, 0.3-0.4 minor
- Relationships: Link related memories when they exist

建筑

项目结构

memory-graph/
├── ts/
│   ├── src/
│   │   ├── cli.ts              # CLI entry point (35+ commands)
│   │   ├── index.ts            # Library exports
│   │   ├── config.ts           # Configuration management
│   │   ├── database.ts         # Database interface
│   │   ├── models.ts           # Data models and schemas
│   │   ├── backends/           # Backend implementations
│   │   │   ├── falkordb-shared.ts  # Shared FalkorDB base class
│   │   │   ├── falkordblite.ts     # Embedded FalkorDBLite
│   │   │   ├── falkordb.ts         # Client-server FalkorDB
│   │   │   ├── bolt-shared.ts      # Shared Bolt protocol base
│   │   │   ├── memgraph.ts         # Memgraph (Bolt protocol)
│   │   │   ├── sqlite.ts           # SQLite fallback
│   │   │   ├── cloud.ts            # Cloud REST API
│   │   │   └── factory.ts          # Backend factory
│   │   ├── tools/              # CLI tool handlers
│   │   ├── intelligence/       # Entity extraction, pattern recognition, context retrieval
│   │   ├── analytics/          # Graph visualization, similarity, learning paths
│   │   ├── proactive/          # Session briefing, predictions, outcome learning
│   │   ├── integration/        # Context capture, project analysis, workflow tracking
│   │   ├── migration/          # Backend-to-backend migration
│   │   ├── sdk/                # Cloud API client SDK
│   │   └── utils/              # Export/import, validation, helpers
│   ├── tests/                  # 97 tests
│   └── package.json
├── docs/                       # Documentation
└── CLAUDE.md                   # Agent instructions

建筑物

cd ts
bun install
bun test                    # Run tests
npx tsc --noEmit            # Type check
bun build src/cli.ts --compile --outfile memorygraph  # Compile binary

导入/迁移

# Import from JSON export
bun run src/cli.ts import --input backup.json --skip-duplicates

# Migrate between backends
bun run src/cli.ts migrate --to sqlite --to-path ./local.db
bun run src/cli.ts migrate --to falkordblite --to-path ./graph.falkor --no-verify
bun run src/cli.ts migrate --to memgraph --to-uri bolt://localhost:7687

软件开发工具包

TypeScript SDK为MemoryGraph Cloud API提供了一个客户端：

import { MemoryGraphClient } from "memorygraph/sdk";

const client = new MemoryGraphClient({ apiKey: "mg_..." });

const memory = await client.createMemory({
  type: "solution",
  title: "Fixed timeout issue",
  content: "Used exponential backoff with retries",
  tags: ["redis", "timeout"],
});

许可证

MIT许可证-请参阅许可证.

从简单开始。需要时升级。永远不要再失去背景。