Not only long-term memory
A memory note cannot tell an agent where a symbol lives or whether an edit is in scope. guu compiles catalogs, retrieves them for the task, and keeps decisions beside that map.
Open source · MCP · Machine-local
guu is not a long-term memory file. Every agent you connect reads the same project context, learns from the work you do together, follows your coding style, and writes memory back only when that memory should change.
build_context for this task--root.
check_gate → PASS or WARN, then edit.
The repository is already there. The agent still starts from zero, guesses the stack, and edits before anyone checked the scope.
It greps the tree and still invents routes, Shopify surfaces, and how the app is deployed.
Every new chat re-explains architecture and decisions you already settled.
Files change before identity, blast radius, or product intent has been looked at.
Four layers. Knowledge describes the project. Memory keeps what you learned. Context fuses them for one task. The gate decides whether an edit may start.
Scanners, parsers, and detectors turn the repo into catalogs: structure, architecture, domain language, patterns, Shopify, and Docker. guu.db is the source of truth. JSON beside it is an export.
Decisions, conventions, and lessons stay on the machine, with the files and commits they belong to. The next build_context only pulls memories that overlap the task.
build_context runs once per task and returns context plus a context_id. Need more? search_knowledge and get_knowledge. Do not recompile unless the task or knowledge version changed.
check_gate returns PASS, WARN, or FAIL. Implementation edits wait for PASS or WARN. Review, plan, and debug skip the coding gate. An empty store blocks until setup and analyze.
Core stack
Native search stays on the machine. Tree-sitter reads the syntax, hybrid retrieval ranks the hits, and SQLite keeps the store. An LLM is optional for catalog enrichment, and it is not on the search path.
Parse
web-tree-sitter turns TypeScript, JavaScript, Ruby, Python, and Go into symbols and call edges. The agent looks up a name before it opens a file.
Retrieve
BM25-lite and vector cosine run on one corpus, then fuse with reciprocal rank fusion. A lookup can also come from the graph, an exact match, or a symbol.
Embed
The native provider is hash: deterministic vectors, no model download, no API key. They live in a SQLite vector index (sqlite-vector).
Store
node:sqlite is guu.db — catalogs, the knowledge graph, memories, and context sessions. Disk exports are written after the database commit.
Connect
One server for Cursor, Claude Code, OpenCode, VS Code, and Antigravity. Tools, guu:// resources, and prompts. Stdio on the laptop, HTTP when you host it.
Graph
GitNexus or a code-review graph when the repo already has one. Otherwise guu’s own graph. Blast radius goes into check_gate only when that analysis actually ran.
The server does not paste the repository into the chat. It hands the agent a task pack built from knowledge and from memory that was already compiled, then stays available while the agent works.
The agent calls build_context once. The pack leads with memories that overlap this task — decisions and lessons from earlier sessions — and the files those memories name. Workflows, patterns, product intent, and your GuuCode style come with it. A different editor, started tomorrow, gets that same pack for the same project.
If the pack is thin, the agent searches with the same context_id: search_knowledge, get_knowledge, sitemap, and symbols. It does not call build_context again, and it does not guess routes, Shopify, or deploy layout that the catalogs already describe.
check_gate looks at the task, the files about to change, and memories that still cover those files. PASS or WARN, then the edit. FAIL stops it. Review, plan, and debug skip the coding gate. An empty store blocks until the project has been analyzed.
Durable lines from the conversation can be extracted as memory candidates. After the code change, the agent assesses the diff. Feature memory is written for a new behavior or a lesson. Knowledge is written when catalogs, routes, or stack facts moved. Neither is written when the turn did not earn it. The next agent — Cursor or Claude or OpenCode — starts from that store.
build_context({ task, mode })
search_knowledge({ context_id, query })
check_gate({ task, file_paths })
auto_feature_memory_update({ change_summary, files_changed })The last call runs only when the assessment says the memory should change. apply_updates: false previews that decision without writing.
Stdio is the default. The IDE spawns guu-mcp. Run this on the app repository the agent will edit, and pass an absolute --root.
The package is @fordeer/cli on GitHub Packages. You need a token with read:packages. The binary is guu.
pnpm add -g @fordeer/cli
guu --version && which guu-mcpsetup writes .guu-project.json, creates guu.db, and installs skill packs. An IDE flag also writes that agent’s MCP config. Without a flag, setup only prints the snippet.
guu setup --root "$APP" --cursor
guu analyze --root "$APP"
guu doctor --root "$APP"The same pattern exists for --claude, --opencode, --vscode, and --antigravity. Add --cursor-global (and the matching global flag) only when that IDE is already installed and you want the user-level config too.
Server name should be unique per app. project and GUU_PROJECT name the data namespace under ~/.guu/data/<project>/. Tools run only when that namespace’s git signature matches this checkout.
{
"mcpServers": {
"guu-your-app": {
"command": "guu-mcp",
"project": "your-app",
"env": { "GUU_PROJECT": "your-app" }
}
}
}Cursor uses .cursor/mcp.json. Claude Code uses .mcp.json with the same shape. Antigravity uses .agents/mcp_config.json. OpenCode uses opencode.json with command as an array and environment instead of env. VS Code uses .vscode/mcp.json with servers and type: "stdio".
Enable the server in the IDE and restart MCP. In chat, ask the agent to call build_context with task check guu MCP. Expect contextReady: true and identityGate.ok: true.
Do not enable stdio and HTTP MCP for the same agent. HTTP is guu start --http, for a shared process — not the command inside Cursor or VS Code.
33 tools · 10 resources. Tools, guu:// resources, and prompts. A peek is not a second briefing, and a briefing is not a dump of the store.
build_context, search_knowledge, get_knowledge, update_knowledge. Modes cover implementation, bugfix, refactor, review, investigation, and architecture.
query for sitemap, symbols, directory, routes, graph, and blast. Resources answer the same questions mid-task without recompiling context.
check_gate before file edits. confirm for a large scope. impact for performance, race, and security risk. Optional GitNexus or CGC blast radius can be passed in — never invented.
Search, save, update, confirm, invalidate, and promote. A memory can point at repo files and commits. Closed memories stop warning the gate.
analyze_project, enrich_project_knowledge, and update_project_knowledge match the CLI. If MCP times out, retry that command with --root.
auto_feature_memory_update and auto_knowledge_update, then an assessment for docs and QA notes. The next session inherits the change.
Measured with pnpm run measure:tokens on all 33 MCP tools. ~tokens is the compacted reply the agent actually receives, estimated as output characters ÷ 4. The heaviest sample is build_context at 637.
| Tool | Def | Args | Output | ~tokens | Sample |
|---|---|---|---|---|---|
| build_context | 2706 | 58 | 2548 | 637 | curated |
| check_gate | 2500 | 178 | 2061 | 515 | curated |
| impact | 1807 | 154 | 1910 | 478 | curated |
| query | 2905 | 45 | 1905 | 476 | curated |
| analyze_project | 1101 | 31 | 1187 | 297 | curated |
| enrich_project_knowledge | 735 | 17 | 1144 | 286 | curated |
| auto_feature_memory_update | 868 | 161 | 947 | 237 | curated |
| guu_code | 829 | 2 | 785 | 196 | auto |
| invalidate_feature_memory | 521 | 72 | 480 | 120 | curated |
| guu_product | 1326 | 2 | 412 | 103 | auto |
| save_memory | 1544 | 38 | 388 | 97 | auto |
| update_project_knowledge | 508 | 2 | 385 | 96 | curated |
| save_feature_memory | 1999 | 299 | 385 | 96 | curated |
| consolidate_feature_memory_episodes | 1049 | 50 | 324 | 81 | curated |
| auto_knowledge_update | 645 | 161 | 315 | 79 | curated |
| agent_rules | 857 | 2 | 143 | 36 | curated |
| list_agent_rules | 404 | 2 | 143 | 36 | auto |
| search_memory | 588 | 42 | 116 | 29 | auto |
| maintain_memory | 385 | 2 | 116 | 29 | auto |
| get_memory_graph | 306 | 52 | 102 | 26 | curated |
| extract_memory | 305 | 2 | 96 | 24 | auto |
| confirm | 477 | 18 | 89 | 22 | curated |
| get_knowledge | 1254 | 91 | 73 | 18 | auto |
| search_knowledge | 1349 | 2 | 60 | 15 | auto |
| forget_agent_rule | 470 | 2 | 57 | 14 | auto |
| remember_agent_rule | 493 | 2 | 46 | 12 | auto |
| search_memory_for_context | 364 | 2 | 45 | 11 | auto |
| get_memory | 327 | 2 | 44 | 11 | auto |
| update_memory | 450 | 40 | 44 | 11 | auto |
| confirm_memory | 324 | 2 | 44 | 11 | auto |
| invalidate_memory | 447 | 2 | 44 | 11 | auto |
| promote_memory | 350 | 2 | 44 | 11 | auto |
| update_knowledge | 456 | 12 | 29 | 7 | auto |
| Every tool once | 30649 | 1549 | 16511 | 4128 |
Def, args, and output are characters. Definitions load once when MCP connects. A normal step is one row, and that reply stays under 700 tokens. The last row sums all 33 tools called in one pass. curated uses a hand-written sample; auto uses arguments generated from the schema.
Not every catalog row belongs in the prompt. The briefing leads with memories that overlap the task and the files they name, then workflows and patterns. Style and product intent stay available without crowding out the evidence.
Decisions and rules with lexical overlap to this task. Zero-overlap rows stay out.
Related paths are promoted into the relevant-file list so the agent opens the right place first.
How this codebase expects the change to be made, retrieved by type when the pack is not enough.
The reply is capped. Further detail comes from search and typed lookups, not another full compile.
A README is a fine briefing for a small project. It stops scaling once the agent must find symbols, remember a decision, and refuse an edit that is out of scope.
build_contextguu.db on this machinecheck_gate PASS or WARN
Use the README when the project is small and a paragraph is the whole briefing.
Use guu when several agents share a real codebase and the next task should be more accurate than the last one.
The default. The IDE spawns guu-mcp. Knowledge and memory stay under your data home. No Docker, no open port.
guu doctor for MCP, graph, embeddings, memoryFor a shared process: guu start --http, or the Docker image when an operator hosts it. Pick one transport per agent.
A normal developer machine. Enrichment can call a model; search and the hash embedding provider do not have to.
@fordeer/cli install.
read:packages for the @fordeer scope.