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]

Loading

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.

---

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