0 Fork 0

Files

T

Riz Ashraf 533adfd41b refactor: consolidate nvim crates, extract server library, and update workspace dependencies

2026-10-04 01:42:59 +01:00

10 KiB

Raw Blame History

Memory MCP Strategic Guidelines

This document outlines the STRATEGY, SEMANTICS, and CASING STANDARDS for using the MCP Memory Server. You do not need to memorize JSON schemas for these tools; they are strictly defined and typed in the tools/list endpoint. Focus purely on WHEN and WHY to use them.

1. Casing & Naming Standards (CRITICAL)

To prevent graph fragmentation and ensure seamless LLM context retrieval:

Entity Types (entity_type): MUST ALWAYS be PascalCase (e.g. DatabaseTable, McpTool, ArchitectureComponent, File, DataStructure).
Relation Types (relation_type): MUST ALWAYS be snake_case (e.g. depends_on, calls, implements, uses, contains).
Field Keys & Properties: MUST ALWAYS be snake_case (e.g. file_path, git_commit, created_at).

Note

The server automatically enforces and migrates incoming entity and relation types to these canonical casing rules on every read and write operation.

2. LLM Token Budgeting & RRF Search Optimization

Token Budgeting (summary_level & max_tokens): When calling list_active_tasks or list_tech_debt, pass summary_level: "compact" or "detailed" and max_tokens: 500 to constrain output size when token context budget is tight.
Reciprocal Rank Fusion (RRF) Omni-Search: omni_search uses Hybrid RRF (BM25 keyword search + Dense Vector Embeddings) to rank results semantically. You do not need exact keyword matches; query conceptually (e.g. "database lock issues").
Delta Session Context (memory://session/delta): Passively read memory://session/delta to get a succinct delta of code changes, tasks, and tech debt recorded during the current working session.
Context Warmup (context_warmup): Trigger the context_warmup prompt at session start to automatically synthesize delta changes, active tasks, tech debt, and pinned files in a single pass.

Tool: get_subgraph
When to use: When you need to understand the complete architectural neighborhood surrounding a specific component, module, or database table.
Behavior: Performs a multi-hop Breadth-First Search (BFS) around a root_node up to a requested depth (e.g. 1 to 3 hops) and returns all connected entities and relations in a single call.

4. Automated Error Fix Auto-Matcher

Tools: log_error_fix, suggest_error_fix, search_error_fixes
When to use: When encountering a build error, test failure, or stack trace. Call suggest_error_fix with the error trace before attempting a fix from scratch.
Behavior: Computes cosine similarity between error trace embeddings and past resolution logs to return top matched solutions, modified files, and git commits.

5. Memory State Checkpointing & Rollbacks

Tools: checkpoint_state, restore_state
When to use: Before initiating a large refactor, running experimental subagent tasks, or executing destructive batch operations.
Behavior: Saves or restores a point-in-time snapshot of graph entities, active tasks, and tech debt backlogs.

6. Symbol Reference Backlinks

Tools: log_code_change, log_error_fix, log_tech_debt
When to use: When logging changes or debt tied to specific code symbols or line boundaries.
Behavior: Accept symbol_references (e.g., ["MemoryState::new", "CreateEntitiesTool"]) and line_range (e.g., "L45-L90"), automatically indexing code references for quick symbol backlink searches.

7. Ephemeral Sticky Notes with TTL

Tools: add_sticky_note, read_sticky_notes, delete_sticky_note, clear_sticky_notes
When to use: For temporary scratchpad items, temporary ports, task IDs, or transient notes.
Behavior: Supports ttl_seconds for auto-expiration and session_only: true for automatic purging when the session ends.

8. Snippet Vault & Domain Tagging

Tools: store_snippet, search_snippets, delete_snippet, tag_snippet
When to use: Store exact multi-line code snippets, Nushell pipelines, or frequently used CLI commands.
Behavior: Guarantees precise syntactic preservation. Use tag_snippet to attach domain tags (e.g., ["rust", "axum", "mcp"]) for category-filtered searches.

9. Context Namespaces (Project Scopes)

Feature: namespace optional parameter
When to use: Isolate graph queries, tasks, and tech debt to specific project scopes (e.g. "mcp-memory").
Behavior: Pass namespace to read_graph, search_nodes, create_entities, or create_relations to isolate items from global scope.

10. Architectural Decision Records (ADRs)

Tools: log_decision, query_decisions, delete_decision
When to use: Whenever making a non-trivial architectural, environmental, or design decision.
Behavior: Permanently stores context, decision, and consequences to prevent future agents from second-guessing choices.

11. Graph Refactoring & Algorithms

Tools: merge_entities, find_orphans, query_graph_path, condense_entity
When to use: Run find_orphans periodically to clean unused nodes. Use merge_entities to combine duplicate concepts. Use query_graph_path to find shortest relational connections between components. Use condense_entity when entity observation counts grow large.

12. Dynamic Learned Preferences

Tools: learn_preference, read_preferences
When to use: When the user specifies personal or repository-specific preferences.
Behavior: Stores key-value behavioral preferences that persist across agent invocations.

13. Pinned Workspaces & Hot Files

Tools: pin_file, unpin_file, list_pinned_files
When to use: Pin 3–5 active working set files to maintain focus in large codebases.

14. Agent Handoffs & Memos

Tools: leave_handoff_memo, read_handoff_memos, clear_handoff_memos
When to use: Leave messages for future agent sessions or inspect pending handoff notes upon waking.

15. Real-time WebSocket Memory Sync

Endpoint: ws://127.0.0.1:3000/ws
Behavior: Broadcasts live state updates and activity notifications to the Brain Monitor UI in real time.

16. Self-Healing Graph Health Sweeper

Tool: sweep_graph_health
When to use: Periodically or before committing major graph changes to audit entity consistency.
Behavior: Detects orphaned nodes (0 relations), computes name similarity to identify near-duplicates (e.g., APIGateway vs ApiGateway), and provides structured merge_entities recommendations or auto-prunes orphans.

17. Causal Lineage & Provenance Tracker

Tool: query_lineage
When to use: When asking "Why was this component modified?" or "What task or ADR led to this code change?"
Behavior: Searches across tasks, ADRs, audit ledger entries, and error fixes to assemble a unified chronological timeline explaining the provenance behind any file, symbol, or commit.

18. Topological Unblocked Task Resolver

Tool: get_next_actionable_tasks
When to use: When orchestrating subagent execution or selecting the next task to work on.
Behavior: Evaluates task dependency DAGs and filters out any blocked tasks, returning only unblocked, actionable tasks ready for immediate execution.

19. Chain-of-Thought & Diagnostic Hypothesis Memory

Tools: log_hypothesis, query_hypotheses
When to use: During complex debugging or root cause analysis.
Behavior: Records hypotheses alongside tested evidence and status (unverified, verified, rejected). Allows subagents to query past diagnostic paths and avoid re-testing disproven hypotheses.

20. Workspace Context Diffing

Tool: diff_context_workspaces
When to use: When switching branches or comparing two saved context workspaces.
Behavior: Returns a structured delta highlighting added, removed, and shared pinned files and active task IDs between two context workspaces.

21. Universal Token Guardrails

Behavior: Automatically caps large MCP resource reads (e.g. memory://graph/entities) and list responses, adding summary headers ("_meta": "Showing 100 of N items") to guarantee output stays within context window limits.

22. LLM Pre-Flight Context Bundle

Tool: get_preflight_context
When to use: At the start of a turn or subagent task to gain total situational awareness in 1 call.
Behavior: Aggregates current active branch, in-progress tasks with acceptance criteria, pinned files, top open tech debts, and active unverified hypotheses into a consolidated executive context bundle.

23. Self-Healing Symbol & Line Range Resolver

Tool: resolve_stale_symbols
When to use: When files have been deleted, moved, or heavily refactored.
Behavior: Verifies graph entities and tech debt symbol references against disk and AST, flagging and auto-healing stale pointers or broken file paths.

24. Subgraph Topology Summarizer

Tool: summarize_subgraph
When to use: When needing a high-density, token-budgeted architectural summary of a module or component neighborhood.
Behavior: Generates a compact Markdown topology tree centered on a root_entity up to depth hops, capped strictly within a requested max_tokens budget.

25. Inter-Agent Signal Bus

Tools: broadcast_agent_signal, query_agent_signals
When to use: For real-time coordination and event-driven communication between concurrent subagents (e.g., PrePushAuditor signaling AUDIT_PASSED to parent agent).
Behavior: Ephemeral TTL-backed signal bus storing structured agent events, payloads, and artifact URIs.

26. Automated Session Checkpoint on Shutdown

Tool: auto_session_checkpoint
When to use: Executed automatically on /shutdown or manually when pausing a session.
Behavior: Captures active tasks, unverified hypotheses, recent commit ledgers, and workspace state into a permanent HandoffMemo for seamless turn-taking and recovery.

27. Hybrid Vector & BM25 Code Search

Tool: search_snippets_hybrid
When to use: When searching the snippet vault for reusable code patterns or Nushell pipelines.
Behavior: Combines BM25 term frequency keyword matching with semantic tag scoring to rank code snippets by relevance.

10 KiB Raw Blame History Unescape Escape