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.

---

Using with Coding Agents

Coding agents already execute shell commands, so they can use MemoryGraph directly. Two steps: install globally, then add instructions.

Install

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

memorygraph is now available from any directory. Data persists in ~/.memorygraph/.

Add Agent Instructions

Paste this into your agent's instruction file (~/.claude/CLAUDE.md, .cursorrules, .windsurfrules, or 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.

Example Session

# 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"

Multi-Project Setup

All projects share ~/.memorygraph/falkordblite.db by default. To isolate per project:

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

Troubleshooting

• Agent not using commands: Use "REQUIRED"/"MUST" in instructions, include exact commands
• Command not found: bun link from ts/, or ensure ~/.local/bin is on PATH
• Memories not persisting: memorygraph config to check path, memorygraph health to verify

---

Why MemoryGraph?

Graph Relationships Make the Difference

Flat storage (CLAUDE.md, vector stores) keeps memories as isolated entries. Graph storage connects them:

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

Query: "What happened with retry logic?" returns the full causal chain, not just individual memories.

When to Use What

---

CLI Commands

Memory Operations

Context Search

Intelligence

Analytics

Proactive

Integration

Temporal

Data Management

---

Backends

Backend Configuration

# 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

Environment Variables

---

Memory Types

Relationship Types

---

Memory Best Practices

Session Workflow

# 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

Add to CLAUDE.md or 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

---

Architecture

Project Structure

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

Building

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

---

Import / Migration

# 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

---

SDK

The TypeScript SDK provides a client for the 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"],
});

---

License

MIT License - see LICENSE.

---

Start simple. Upgrade when needed. Never lose context again.