memory-graph

name

memory-graph

description

Agent-agnostic personal knowledge graph stored as markdown files with YAML frontmatter. Use when you need persistent context about the user's life, projects, tools, people, concepts, or decisions — especially across agent resets or switches. Also use when logging significant activity, searching for context before starting work, creating knowledge nodes for new topics, discovering connections between existing nodes (backfill), or rebuilding indexes. Triggers include needing user context, logging work, "remember this", "what do I know about X", creating/updating knowledge entries, and periodic memory maintenance.

Memory Graph

A file-based personal knowledge graph at ~/memory/. Any agent can read/write. Human-browsable.

Structure

~/memory/
├── README.md              # full architecture doc
├── graph/                 # knowledge nodes
│   ├── people/
│   ├── projects/
│   ├── concepts/
│   ├── places/
│   ├── tools/
│   └── <any-category>/    # extend freely
├── log/                   # daily activity logs
│   └── YYYY-MM-DD.md
├── indexes/               # computed — NEVER edit directly
│   ├── memory.db          # SQLite (primary index, FTS5 search)
│   └── graph.html         # interactive graph visualization
├── backfill/              # connection discovery
│   ├── suggestions.md
│   └── history.md
└── scripts/               # symlinks → skill's scripts/ directory
    ├── rebuild-indexes.js  # full or incremental index rebuild
    ├── suggest-backfill.js # scoped connection discovery (+ QMD semantic)
    ├── query.js            # CLI structural query tool
    ├── briefing.js         # context assembly for agents
    ├── lint.js             # graph validation and health checks
    ├── visualize.js        # D3.js graph visualization generator
    ├── commit.js           # git auto-commit for graph/log changes
    └── promote.js          # log-to-node promotion suggestions

Script location: Scripts live in the skill directory (scripts/). ~/memory/scripts/ contains symlinks to them. All scripts support MEMORY_ROOT env var (defaults to ~/memory) so they resolve paths correctly regardless of where they're installed.

Setup

If ~/memory/ does not exist, read references/setup.md and follow the scaffolding steps. This creates the folder structure, symlinks scripts, seeds initial nodes, and builds indexes.

If ~/memory/ already exists, proceed to Operations below.

Node Format

Every node is a markdown file with YAML frontmatter:

---
type: project
created: 2026-03-20
updated: 2026-03-20
tags: [side-project, saas]
status: active
relations:
  - { to: people/someone, type: owner }
  - { to: tools/nextjs, type: built-with }
---

# Title

Free-form body.

## Changelog

- 2026-03-20: Created node

Required Fields

• type — matches parent folder name
• created — ISO date

Recommended Fields

• updated — ISO date, last time node content was meaningfully changed. Used for staleness tracking.

Optional Fields

• tags — flat list for categorization
• status — active, archived, idea, done, etc.
• relations — list of { to, type } objects. to is relative path within graph/ (no .md). type is any string.
• Add any other fields freely — unknown fields are preserved

Relation Type Taxonomy

Suggested standard types (non-standard types trigger info-level lint warnings):

• Structural: uses, built-with, part-of, contains
• Ownership: creator, owner, maintainer
• Conceptual: related-to, inspired-by, alternative-to, core-concept-of, core-value-of
• Temporal: led-to, preceded-by, evolved-into
• Contextual: home-of, lives-in, works-at

Bidirectionality

Write a relation on one side only. The index script computes the reverse.

Changelog Convention

Nodes can have a ## Changelog section at the bottom of the body. Format:

- YYYY-MM-DD: description of what changed

Node Templates

Templates for common node types are in the skill's templates/ directory:

• person.md, project.md, tool.md, concept.md, place.md

Use these as starting points when creating new nodes. Copy and edit — don't modify the templates themselves.

Operations

1. Read for Context (Session Start)

# Check recent activity
cat ~/memory/log/$(date +%Y-%m-%d).md

# Context briefing for a node (full content + relations + recent logs)
node ~/memory/scripts/briefing.js --node projects/flowmind

# Topic briefing (search-based)
node ~/memory/scripts/briefing.js --topic "immutability"

# Semantic search (if QMD is installed — best for natural language queries)
qmd vsearch "trust and data integrity"     # vector similarity
qmd query "what connects X and Y"          # hybrid + reranking

# Structural search
node ~/memory/scripts/query.js --search "keyword"

# Node details with all relations
node ~/memory/scripts/query.js --node projects/flowmind

# All nodes related to something
node ~/memory/scripts/query.js --related-to people/abdullah

# Filter by type and status
node ~/memory/scripts/query.js --type project --status active

# Browse by tag
node ~/memory/scripts/query.js --tag side-project

# Recently modified nodes
node ~/memory/scripts/query.js --recent 7

# Stale nodes (not updated in N days)
node ~/memory/scripts/query.js --stale 30

# Graph overview
node ~/memory/scripts/query.js --stats

2. Create a Node

1. Check if node already exists: ls ~/memory/graph/<category>/
2. Copy a template from the skill's templates/ directory to ~/memory/graph/<category>/<name>.md
3. Fill in frontmatter + body (set created and updated to today)
4. Scan existing nodes for potential relations (shared tags, mentions)
5. Add discovered relations with type: suggested if uncertain
6. Log the creation in today's activity log
7. Rebuild indexes: node ~/memory/scripts/rebuild-indexes.js --incremental
8. If QMD is installed: qmd update && qmd embed (refreshes semantic search)

3. Update a Node

1. Read the current node
2. Update frontmatter and/or body
3. Update the updated field to today's date
4. Add entry to ## Changelog section if significant
5. Log the update
6. Rebuild indexes: node ~/memory/scripts/rebuild-indexes.js --incremental

4. Log Activity

Append to ~/memory/log/YYYY-MM-DD.md (create if needed):

- **HH:MM** [agent-name] Description {ref: path/to/node, path/to/other}

{ref: ...} references are backfill signals — they hint at connections between nodes.

5. Backfill (Discover Missing Connections)

# Rebuild indexes first (if not recently done)
node ~/memory/scripts/rebuild-indexes.js --incremental

# Generate suggestions (scoped — uses tags, FTS, log co-refs, + QMD semantic)
node ~/memory/scripts/suggest-backfill.js                                  # all nodes
node ~/memory/scripts/suggest-backfill.js --scope recent                   # last 7 days only
node ~/memory/scripts/suggest-backfill.js --scope node:projects/flowmind   # specific node
node ~/memory/scripts/suggest-backfill.js --no-qmd                         # skip semantic search

# Rebuild with automatic scoped backfill on changed nodes
node ~/memory/scripts/rebuild-indexes.js --incremental --with-backfill

Review ~/memory/backfill/suggestions.md. Accept by adding the relation to the node's frontmatter. Reject by logging in backfill/history.md.

6. Lint (Validate Graph Health)

node ~/memory/scripts/lint.js            # check for issues
node ~/memory/scripts/lint.js --fix      # auto-fix (adds missing updated fields)

Checks: missing required fields, broken relations, orphan nodes, duplicate titles, non-standard relation types.

7. Visualize

node ~/memory/scripts/visualize.js       # generates ~/memory/indexes/graph.html
open ~/memory/indexes/graph.html         # view in browser

Interactive D3.js force-directed graph. Nodes colored by type, sized by connections. Click for details.

8. Git Backing

node ~/memory/scripts/commit.js                        # auto-commit graph/ and log/ changes
node ~/memory/scripts/commit.js --message "custom msg"  # with custom message

Stages graph/, log/, backfill/history.md, and README.md changes, commits with descriptive message. Does NOT auto-push.

9. Log Promotion

node ~/memory/scripts/promote.js           # find recurring topics without nodes
node ~/memory/scripts/promote.js --min 5   # raise mention threshold
node ~/memory/scripts/promote.js --days 30 # only recent logs

Scans logs for entities mentioned 3+ times without existing nodes. Suggests node creation.

10. Add a New Category

Create a folder under graph/. No config changes. Indexes adapt on rebuild.

Rules

1. Read before writing. Check if a node exists before creating a duplicate.
2. Log significant work. Append to log/YYYY-MM-DD.md when you do something significant.
3. Use refs in logs. If your work touches existing concepts/projects, add {ref: ...}.
4. Scan for connections. When creating a node, check for related nodes (shared tags, mentions).
5. Never edit indexes/. Run the rebuild script instead.
6. Add fields freely. If a node needs a field that doesn't exist yet, just add it.
7. Add categories freely. Need graph/recipes/? Create the folder. No config changes.
8. Preserve unknown fields. If a node has fields you don't recognize, leave them.
9. Use suggested type for uncertain relations. Let a human or another agent confirm.
10. One-side relations only. Write on whichever node feels natural. Index computes the reverse.
11. Keep the body useful. Frontmatter is for machines. The markdown body is for humans.
12. Set updated on changes. Keep the updated field current for temporal tracking.
13. Use standard relation types. Prefer the taxonomy above. Run lint.js to check.