Skip to content

feat: RAG memory graph with interlinked traversal #13

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ForLoopCodes merged 1 commit into from
Mar 3, 2026
Merged

feat: RAG memory graph with interlinked traversal #13

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 11 additions & 1 deletion INSTRUCTIONS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,16 +26,20 @@ The MCP server is built with TypeScript and communicates over stdio using the Mo
- `static-analysis.ts` - Native linter runner (tsc, eslint, py_compile, cargo check, go vet).
- `propose-commit.ts` - Code gatekeeper validating headers, FEATURE tag, no inline comments, nesting, file length.
- `feature-hub.ts` - Obsidian-style feature hub navigator with bundled skeleton views.
- `memory-tools.ts` - Memory graph MCP wrappers (upsert, relate, search, prune, interlink, traverse).

The memory graph is a **Retrieval-Augmented Generation (RAG)** system. Agents MUST use `search_memory_graph` at the start of every task to retrieve prior context, and persist learnings with `upsert_memory_node` and `create_relation` after completing work. This prevents redundant exploration and builds cumulative knowledge across sessions.

**Core Layer** (continued):

- `hub.ts` - Wikilink parser for `[[path]]` links, cross-link tags, hub discovery, orphan detection.
- `memory-graph.ts` - In-memory property graph with JSON persistence, decay scoring, and auto-similarity edges.

**Git Layer** (`src/git/`):

- `shadow.ts` - Shadow restore point system for undo without touching git history.

**Entry Point**: `src/index.ts` registers 11 MCP tools and starts the stdio transport. Accepts an optional CLI argument for the target project root directory (defaults to `process.cwd()`).
**Entry Point**: `src/index.ts` registers 17 MCP tools and starts the stdio transport. Accepts an optional CLI argument for the target project root directory (defaults to `process.cwd()`).

## Environment Variables

Expand Down Expand Up @@ -136,6 +140,12 @@ Strict order within every file:
| `list_restore_points` | See undo history. |
| `undo_change` | Revert a bad AI change without touching git. |
| `get_feature_hub` | Browse feature graph hubs. Find orphaned files. |
| `upsert_memory_node` | Create/update memory nodes (concept, file, symbol, note) with auto-embedding. |
| `create_relation` | Create typed edges between memory nodes (depends_on, implements, etc). |
| `search_memory_graph` | Semantic search + graph traversal across 1st/2nd-degree neighbors. |
| `prune_stale_links` | Remove decayed edges (e^(-λt)) and orphan nodes periodically. |
| `add_interlinked_context` | Bulk-add nodes with auto-similarity linking (cosine ≥ 0.72). |
| `retrieve_with_traversal` | Start from a node, walk outward, return scored neighbors by decay and depth. |

## Anti-Patterns to Avoid

Expand Down
17 changes: 14 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

Semantic Intelligence for Large-Scale Engineering.

Context+ is an MCP server designed for developers who demand 99% accuracy. By combining Tree-sitter AST parsing, Spectral Clustering, and Obsidian-style linking, Context+ turns a massive codebase into a searchable, hierarchical feature graph.
Context+ is an MCP server designed for developers who demand 99% accuracy. By combining RAG, Tree-sitter AST, Spectral Clustering, and Obsidian-style linking, Context+ turns a massive codebase into a searchable, hierarchical feature graph.

https://github.com/user-attachments/assets/a97a451f-c9b4-468d-b036-15b65fc13e79

Expand Down Expand Up @@ -39,6 +39,17 @@ https://github.com/user-attachments/assets/a97a451f-c9b4-468d-b036-15b65fc13e79
| `list_restore_points` | List all shadow restore points created by `propose_commit`. Each captures file state before AI changes. |
| `undo_change` | Restore files to their state before a specific AI change. Uses shadow restore points. Does not affect git. |

### Memory & RAG

| Tool | Description |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `upsert_memory_node` | Create or update a memory node (concept, file, symbol, note) with auto-generated embeddings. |
| `create_relation` | Create typed edges between nodes (relates_to, depends_on, implements, references, similar_to, contains). |
| `search_memory_graph` | Semantic search with graph traversal — finds direct matches then walks 1st/2nd-degree neighbors. |
| `prune_stale_links` | Remove decayed edges (e^(-λt) below threshold) and orphan nodes with low access counts. |
| `add_interlinked_context` | Bulk-add nodes with auto-similarity linking (cosine ≥ 0.72 creates edges automatically). |
| `retrieve_with_traversal` | Start from a node and walk outward — returns all reachable neighbors scored by decay and depth. |

## Setup

### Quick Start (npx / bunx)
Expand Down Expand Up @@ -125,9 +136,9 @@ npm run build

Three layers built with TypeScript over stdio using the Model Context Protocol SDK:

**Core** (`src/core/`) - Multi-language AST parsing (tree-sitter, 43 extensions), gitignore-aware traversal, Ollama vector embeddings with disk cache, wikilink hub graph.
**Core** (`src/core/`) - Multi-language AST parsing (tree-sitter, 43 extensions), gitignore-aware traversal, Ollama vector embeddings with disk cache, wikilink hub graph, in-memory property graph with decay scoring.

**Tools** (`src/tools/`) - 11 MCP tools exposing structural, semantic, and operational capabilities.
**Tools** (`src/tools/`) - 17 MCP tools exposing structural, semantic, operational, and memory graph capabilities.

**Git** (`src/git/`) - Shadow restore point system for undo without touching git history.

Expand Down
12 changes: 11 additions & 1 deletion landing/src/app/api/instructions/route.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,16 +28,20 @@ The MCP server is built with TypeScript and communicates over stdio using the Mo
- \`static-analysis.ts\` - Native linter runner (tsc, eslint, py_compile, cargo check, go vet).
- \`propose-commit.ts\` - Code gatekeeper validating headers, FEATURE tag, no inline comments, nesting, file length.
- \`feature-hub.ts\` - Obsidian-style feature hub navigator with bundled skeleton views.
- \`memory-tools.ts\` - Memory graph MCP wrappers (upsert, relate, search, prune, interlink, traverse).

The memory graph is a **Retrieval-Augmented Generation (RAG)** system. Agents MUST use \`search_memory_graph\` at the start of every task to retrieve prior context, and persist learnings with \`upsert_memory_node\` and \`create_relation\` after completing work. This prevents redundant exploration and builds cumulative knowledge across sessions.

**Core Layer** (continued):

- \`hub.ts\` - Wikilink parser for \`[[path]]\` links, cross-link tags, hub discovery, orphan detection.
- \`memory-graph.ts\` - In-memory property graph with JSON persistence, decay scoring, and auto-similarity edges.

**Git Layer** (\`src/git/\`):

- \`shadow.ts\` - Shadow restore point system for undo without touching git history.

**Entry Point**: \`src/index.ts\` registers 11 MCP tools and starts the stdio transport. Accepts an optional CLI argument for the target project root directory (defaults to \`process.cwd()\`).
**Entry Point**: \`src/index.ts\` registers 17 MCP tools and starts the stdio transport. Accepts an optional CLI argument for the target project root directory (defaults to \`process.cwd()\`).

## Environment Variables

Expand Down Expand Up @@ -138,6 +142,12 @@ Strict order within every file:
| \`list_restore_points\` | See undo history. |
| \`undo_change\` | Revert a bad AI change without touching git. |
| \`get_feature_hub\` | Browse feature graph hubs. Find orphaned files. |
| \`upsert_memory_node\` | Create/update memory nodes (concept, file, symbol, note) with auto-embedding. |
| \`create_relation\` | Create typed edges between memory nodes (depends_on, implements, etc). |
| \`search_memory_graph\` | Semantic search + graph traversal across 1st/2nd-degree neighbors. |
| \`prune_stale_links\` | Remove decayed edges (e^(-λt)) and orphan nodes periodically. |
| \`add_interlinked_context\` | Bulk-add nodes with auto-similarity linking (cosine ≥ 0.72). |
| \`retrieve_with_traversal\` | Start from a node, walk outward, return scored neighbors by decay and depth. |

## Anti-Patterns to Avoid

Expand Down
2 changes: 1 addition & 1 deletion landing/src/app/layout.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ import "./globals.css";
export const metadata: Metadata = {
title: "Context+ // Semantic Intelligence for Large-Scale Engineering",
description:
"MCP server designed for developers who demand 99% accuracy. Tree-sitter AST parsing, Spectral Clustering, and Obsidian-style linking.",
"MCP server designed for developers who demand 99% accuracy. RAG, Treesitter AST, Spectral Clustering, and Obsidian-style linking.",
Copy link

Copilot AI Mar 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Spelling/branding inconsistency: the project uses “Tree-sitter” elsewhere, but this copy uses “Treesitter”. Consider standardizing to “Tree-sitter” for consistency and searchability.

Suggested change
"MCP server designed for developers who demand 99% accuracy. RAG, Treesitter AST, Spectral Clustering, and Obsidian-style linking.",
"MCP server designed for developers who demand 99% accuracy. RAG, Tree-sitter AST, Spectral Clustering, and Obsidian-style linking.",

Copilot uses AI. Check for mistakes.
icons: {
icon: "/icon.png",
},
Expand Down
4 changes: 2 additions & 2 deletions landing/src/app/page.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -158,7 +158,7 @@ export default async function Home() {
}}
>
Context+ is an MCP server designed for developers who demand 99%
accuracy. By combining Tree-sitter AST parsing & Spectral
accuracy. By combining RAG, Treesitter AST & Spectral
Copy link

Copilot AI Mar 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Spelling/branding inconsistency: this sentence uses “Treesitter”, but other docs (e.g. README) use “Tree-sitter”. Consider using “Tree-sitter” consistently.

Suggested change
accuracy. By combining RAG, Treesitter AST & Spectral
accuracy. By combining RAG, Tree-sitter AST & Spectral

Copilot uses AI. Check for mistakes.
Clustering, Context+ turns a massive codebase into a searchable,
hierarchical graph.
</p>
Expand Down Expand Up @@ -221,7 +221,7 @@ export default async function Home() {
Context+ guarantees minimal context bloat. It gives your agent deep
semantic understanding of your codebase, from AST parsing and symbol
navigation to blast radius analysis and commit validation. Nothing
misses the context.
misses the context, with RAG.
</p>
<table
style={{
Expand Down
2 changes: 0 additions & 2 deletions landing/src/components/IdeSetup.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,8 +33,6 @@ function buildConfig(runner: string, ideId: string): string {
OLLAMA_EMBED_MODEL: "nomic-embed-text",
OLLAMA_CHAT_MODEL: "gemma2:27b",
OLLAMA_API_KEY: "YOUR_OLLAMA_API_KEY",
CONTEXTPLUS_EMBED_BATCH_SIZE: "8",
CONTEXTPLUS_EMBED_TRACKER: "true",
},
},
},
Expand Down
17 changes: 14 additions & 3 deletions landing/src/components/InstructionsSection.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,16 +30,20 @@ The MCP server is built with TypeScript and communicates over stdio using the Mo
- \`static-analysis.ts\` - Native linter runner (tsc, eslint, py_compile, cargo check, go vet).
- \`propose-commit.ts\` - Code gatekeeper validating headers, FEATURE tag, no inline comments, nesting, file length.
- \`feature-hub.ts\` - Obsidian-style feature hub navigator with bundled skeleton views.
- \`memory-tools.ts\` - Memory graph MCP wrappers (upsert, relate, search, prune, interlink, traverse).

The memory graph is a **Retrieval-Augmented Generation (RAG)** system. Agents MUST use \`search_memory_graph\` at the start of every task to retrieve prior context, and persist learnings with \`upsert_memory_node\` and \`create_relation\` after completing work. This prevents redundant exploration and builds cumulative knowledge across sessions.

**Core Layer** (continued):

- \`hub.ts\` - Wikilink parser for \`[[path]]\` links, cross-link tags, hub discovery, orphan detection.
- \`memory-graph.ts\` - In-memory property graph with JSON persistence, decay scoring, and auto-similarity edges.

**Git Layer** (\`src/git/\`):

- \`shadow.ts\` - Shadow restore point system for undo without touching git history.

**Entry Point**: \`src/index.ts\` registers 11 MCP tools and starts the stdio transport. Accepts an optional CLI argument for the target project root directory (defaults to \`process.cwd()\`).
**Entry Point**: \`src/index.ts\` registers 17 MCP tools and starts the stdio transport. Accepts an optional CLI argument for the target project root directory (defaults to \`process.cwd()\`).

## Environment Variables

Expand Down Expand Up @@ -140,6 +144,12 @@ Strict order within every file:
| \`list_restore_points\` | See undo history. |
| \`undo_change\` | Revert a bad AI change without touching git. |
| \`get_feature_hub\` | Browse feature graph hubs. Find orphaned files. |
| \`upsert_memory_node\` | Create/update memory nodes (concept, file, symbol, note) with auto-embedding. |
| \`create_relation\` | Create typed edges between memory nodes (depends_on, implements, etc). |
| \`search_memory_graph\` | Semantic search + graph traversal across 1st/2nd-degree neighbors. |
| \`prune_stale_links\` | Remove decayed edges (e^(-λt)) and orphan nodes periodically. |
| \`add_interlinked_context\` | Bulk-add nodes with auto-similarity linking (cosine ≥ 0.72). |
| \`retrieve_with_traversal\` | Start from a node, walk outward, return scored neighbors by decay and depth. |

## Anti-Patterns to Avoid

Expand Down Expand Up @@ -251,8 +261,9 @@ export default function InstructionsSection() {
}}
>
Copy the instruction file into your project root to teach your agent
fast execute mode, line-numbered symbol retrieval, strict formatting
rules, and anti-patterns that keep context lean and precise.
RAG memory traversal &amp; blast radius analysis that keep context
lean &amp; precise. Or don&apos;t, Context+ already includes the
instructions in the new versions.
</p>

<div
Expand Down
30 changes: 24 additions & 6 deletions landing/src/components/IsometricDiagram.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -83,15 +83,33 @@ const functions = [
desc: "Lightweight git worktree operations",
color: "#999999",
},
{
id: "memory-search",
label: "Memory Search",
desc: "RAG-powered search with graph traversal",
color: "#2a4a6a",
},
{
id: "memory-upsert",
label: "Memory Upsert",
desc: "Persist learned context as graph nodes",
color: "#3a5a7a",
},
{
id: "memory-traverse",
label: "Graph Traverse",
desc: "Walk linked nodes by relation and decay",
color: "#4a6a8a",
},
];

function getCardConfig(width: number) {
if (width >= 1800) return { cardSize: 360, stackDx: -28, stackDy: 28 };
if (width >= 1400) return { cardSize: 300, stackDx: -24, stackDy: 24 };
if (width >= 1025) return { cardSize: 250, stackDx: -20, stackDy: 20 };
if (width >= 850) return { cardSize: 220, stackDx: -18, stackDy: 18 };
if (width >= 500) return { cardSize: 240, stackDx: -18, stackDy: 18 };
return { cardSize: 220, stackDx: -16, stackDy: 16 };
if (width >= 1800) return { cardSize: 360, stackDx: -24, stackDy: 24 };
if (width >= 1400) return { cardSize: 300, stackDx: -21, stackDy: 21 };
if (width >= 1025) return { cardSize: 250, stackDx: -18, stackDy: 18 };
if (width >= 850) return { cardSize: 220, stackDx: -16, stackDy: 16 };
if (width >= 500) return { cardSize: 240, stackDx: -16, stackDy: 16 };
return { cardSize: 220, stackDx: -14, stackDy: 14 };
}

export default function IsometricDiagram() {
Expand Down
57 changes: 57 additions & 0 deletions landing/src/components/ToolDiagram.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -314,6 +314,63 @@ export default function ToolDiagram() {
</div>
))}
</div>
<div style={{ marginTop: 16, position: "relative" }}>
<div
style={{
height: 100,
borderRadius: 20,
overflow: "hidden",
position: "relative",
background: "var(--panel-bg)",
}}
>
<svg
style={{ position: "absolute", inset: 0, width: "100%", height: "100%" }}
xmlns="http://www.w3.org/2000/svg"
>
<defs>
<pattern
id={`diag-rag-bg-${isDark ? "dark" : "light"}`}
width="6"
height="6"
patternUnits="userSpaceOnUse"
patternTransform="rotate(45)"
>
<line
x1="0"
y1="0"
x2="0"
y2="6"
stroke={isDark ? "#000000" : "#000000"}
Copy link

Copilot AI Mar 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This ternary is redundant: stroke is set to #000000 for both dark and light modes, which likely wasn’t intended and makes the conditional misleading. Consider either removing the conditional or using different stroke colors for each theme.

Suggested change
stroke={isDark ? "#000000" : "#000000"}
stroke="#000000"

Copilot uses AI. Check for mistakes.
strokeWidth="1"
/>
</pattern>
</defs>
<rect width="100%" height="100%" fill={`url(#diag-rag-bg-${isDark ? "dark" : "light"})`} />
</svg>
<span
style={{
position: "absolute",
top: "50%",
left: "50%",
transform: "translate(-50%, -50%)",
fontSize: 13,
fontWeight: 500,
color: isDark ? "#ffffff" : "#000000",
fontFamily: "var(--font-geist-pixel-square)",
letterSpacing: "-0.02em",
backdropFilter: "blur(8px)",
WebkitBackdropFilter: "blur(8px)",
background: "var(--panel-bg)",
borderRadius: 9999,
padding: "2px 8px",
border: "none",
}}
>
RAG Functions
</span>
</div>
</div>
</>
);
}
Loading