MindGraph

Every AI agent should ask memory before asking the filesystem.

MindGraph is a local-first AI memory engine for agents — part of the LocalMinds ecosystem. It remembers what your team learned — architecture decisions, gotchas, conventions — and tells the agent which files to read before it starts exploring the repo.

npm install @localminds/mindgraph
npx mindgraph init
npx mindgraph mcp install   # teach Cursor / Claude to retrieve first

Why it's different

| Typical RAG | MindGraph | |-------------|-----------| | Flat document chunks | Knowledge graph — memories linked by relationships | | Semantic search only | Hybrid retrieval — keyword + vectors + graph traversal | | Overwrites old facts | Versioning — supersedes chains preserve history | | Cloud, per-user | Local-first, git-shared — memories live in your repo | | "Find similar text" | "What is connected, current, and relevant?" |

The shift

Without MindGraph:  Question → read 200 files → understand
With MindGraph:     Question → retrieve() → read 6 relevant files → answer

MindGraph doesn't replace your codebase. It tells the agent where to look based on what was already learned.

Quick start

import { MindGraph } from '@localminds/mindgraph';

const memory = await MindGraph.open({ root: process.cwd() });

// 1) Before the agent reads anything
const ctx = await memory.retrieve({
  query: 'How does authentication work?',
});
console.log(ctx.summaryForPrompt);  // inject into agent prompt
console.log(ctx.fileHints);           // files to read first

// 2) During chat — buffer learnings
const session = memory.session({ conversationId: 'chat-42' });
session.observe('Auth middleware must run before tenant context.');

// 3) When done — persist to the graph
await session.end();

CLI equivalent:

mindgraph retrieve "How does auth work?"
mindgraph observe "Auth middleware must run before tenant context."
mindgraph consolidate

See your memory graph

Explore how memories, entities, and relationships connect:

mindgraph graph --open

Opens an interactive viewer at .mindgraph/graph.html:

• Blue dots — memories and decisions
• Green diamonds — entities (AuthService, BillingService, …)
• Red edges — supersession chains (old → new belief)
• Dashed edges — inferred relationships (rebuildable)
• Hover any node for full text, confidence, and file hints

mindgraph graph --json          # export raw graph data
mindgraph graph --out ./graph.html --open

In code:

const html = memory.graphHtml();       // standalone HTML string
const data = memory.exportGraph();     // { nodes, edges }

Integrate in 5 minutes

Cursor / Claude (MCP)

npx mindgraph mcp install

Agents call memory_retrieve before Read/Grep/Glob.

Chat product (library)

const memory = await MindGraph.open({
  root: workspacePath,
  llm: yourLlm,           // optional — smarter consolidation
  embedder: yourEmbedder, // optional — semantic retrieval
});

// On each message, before filesystem access:
const ctx = await memory.retrieve({
  query: userMessage,
  context: { file: activeFilePath },
});

Shell / non-Node agents

mindgraph retrieve "tenant auth bug" --file src/auth/middleware.ts

Full integration guide: docs/INTEGRATION.md

Examples: docs/examples/

How retrieval works

flowchart LR
  Q[User query] --> S[Semantic + keyword seeds]
  S --> G[Graph expansion]
  G --> R[Relationship-aware ranking]
  R --> C[Context for agent]

1. Find entry-point memories (keyword + optional embeddings)
2. Walk the graph — follow mentions, supersedes, related_to, etc.
3. Rank by relevance, resolve superseded beliefs, boost current file context
4. Return summaryForPrompt + fileHints

Memories are the knowledge. The graph is the structure around them.

Architecture deep-dive: docs/ARCHITECTURE.md

Team memory (git-backed)

Share learnings across your team — committed to the repo, auditable via git log:

mindgraph config --sharing team
mindgraph observe "We use Clerk, not Supabase, for auth."
mindgraph consolidate
git add .mindgraph/nodes .mindgraph/graph && git commit -m "Add auth memory"

Teammates: git pull → mindgraph sync

Unlike cloud memory products, your team's knowledge stays in the repo — portable, mergeable, and private.

Commit synchronization

Commit reconciliation is a package operation, so library consumers do not need access to MindGraph's store:

const report = await memory.syncCommits({
  maxCommits: 5,
  maxFilesPerCommit: 10,
});
console.log(report.lastProcessedRef, report.commitsRemaining);

The first call initializes the ignored machine-local cursor at HEAD instead of scanning the repository's entire history. Use fromRef for an explicit, bounded backfill. Every batch processes the oldest pending commits first and advances the cursor only through successful processing.

The file nodes and co_changed_with edges produced by this operation are a local derived index. They are rebuilt independently on each machine and are not team-shared through .mindgraph/nodes or .mindgraph/graph/edges.

CLI reference

| Command | Purpose | |---------|---------| | mindgraph init | Create .mindgraph/ store | | mindgraph retrieve <query> | Get relevant memories | | mindgraph observe <text> | Buffer a learning | | mindgraph consolidate | Persist observations | | mindgraph graph --open | Interactive memory graph | | mindgraph rebuild-index | Rebuild inferred edges | | mindgraph sync | Import team memories after git pull | | mindgraph index-commits --max-commits 5 | Reconcile oldest pending commits | | mindgraph mcp | Start MCP server |

What's included

• Knowledge graph (memories, decisions, entities, relationships)
• Hybrid retrieval (keyword + embedder + typed graph traversal)
• Supersession versioning with history preserved
• Git-backed team sharing
• Observation → consolidate lifecycle
• Interactive graph viewer
• CLI + MCP + library API
• Pluggable LlmPort, Embedder, AppGraphPort, MemoryStore

What's not (yet)

• Built-in code/AST graph (bring your own via AppGraphPort)
• Automatic consolidation triggers (you decide when session.end() runs)
• LLM-powered conflict review queue

See docs/ARCHITECTURE.md and .cursor/rules/ for the roadmap.

Develop

git clone https://github.com/presencewebdesign/mindgraph.git
cd mindgraph && npm install && npm test

CONTRIBUTING.md · MIT LICENSE