ContextMarmot
A graph-based memory engine for agentic systems. Structured context over MCP, instead of raw files.
Agents Are Drowning in Files
The Problem
Coding agents burn tokens re-reading files to rebuild context that already existed two turns ago. Raw files are the worst possible representation: unstructured, redundant, and oblivious to the relationships that actually matter.
Conversation history decays. Ad-hoc retrieval returns disconnected chunks. The agent ends up exploring broadly, paying for it, and still missing the edge that would have answered the question in one hop.
The Graph
ContextMarmot gives agents a persistent knowledge graph: nodes are Obsidian-compatible markdown with YAML frontmatter and [[wikilinks]], edges are typed and directed. Agents query and write via five MCP tools and get back a compacted subgraph, not a file dump.
Agent → MCP Server → Embed + Search + Traverse + Compact → XML contextWhat's in the Box
A single Go binary. Zero CGo, zero runtime dependencies. Everything below ships in one build.
Semantic Search
Embedding index with graph-traversal expansion. Ask in natural language, get a connected subgraph instead of a pile of chunks.
Typed, Directed Edges
Structural edges (contains, imports, extends, implements) stay acyclic. Behavioral edges are free to loop. The graph enforces the difference.
Token-Budget Compaction
Results are compacted into XML that fits your context window, with full / compact / truncated tiers chosen automatically.
CRUD Classifier
Writes are auto-classified as ADD, UPDATE, SUPERSEDE, or NOOP using embeddings plus an optional LLM tiebreaker.
Multi-Namespace Graphs
Projects stay isolated. Bridge manifests describe cross-namespace and cross-vault edges so a repo graph can talk to a team graph.
Static Analysis Indexer
Parses Go (full AST), TypeScript, and 30+ languages into graph nodes with typed edges. No manual authoring required.
The Graph, Up Close
An embedded D3 web UI ships with the binary. Filter, search, overlay heat maps, group by folder, and curate the graph through a chat interface with slash commands and node-reference pills.
Same Quality. Lower Cost.
Evaluated on 20 code-comprehension questions from the SWE-QA benchmark across django, flask, pytest, and requests. The graph acts as a navigation map — agents query it first, then read only the files and line ranges it identifies.
| Metric | Vanilla (file tools) | Hybrid (ContextMarmot) | Δ |
|---|---|---|---|
| Answer quality (1–5) | 4.62 | 4.62 | identical |
| Tokens per question | 151,327 | 95,876 | −37% |
| Cost per question | $0.1065 | $0.0834 | −22% |
| Avg turns | 7.5 | 6.9 | −8% |
Full methodology and per-question breakdown in docs/benchmark.md.
How It Works
Index
marmot index runs static analysis on your source and builds a graph of nodes with typed edges, stored as Obsidian-compatible markdown.
Query
Agents call context_query over MCP with a natural-language question. The engine embeds, searches, and seeds a traversal.
Traverse
BFS expands along hot edges first. A heat map tracks co-access frequency with exponential decay so the graph learns which paths matter.
Compact
Results are serialized to XML, pruned to the token budget, and returned as a self-contained subgraph the agent can reason over.
Give Your Agents a Memory
ContextMarmot is Apache 2.0, open source, and part of how we ship reliable agent workflows at Cloud Gatherer Labs. Clone the repo, run marmot init, and wire it into your coding agent today.