mcp-memory-management
Guide for using Gaia's MCP memory tools (remember/recall) with session-level and persistent storage. Use when debugging, implementing features, or making decisions.
When & Why to Use This Skill
This Claude skill provides a sophisticated memory management system using Gaia's MCP tools to handle both session-level and persistent project-wide storage. It enables AI agents to store, search, and retrieve critical information such as architectural decisions, bug fixes, and configuration patterns, ensuring long-term context retention and more informed decision-making across development cycles.
Use Cases
- Persistent Issue Resolution: Documenting root causes and fixes for complex bugs to prevent regressions and avoid repeating the same troubleshooting steps in future sessions.
- Architectural Decision Records (ADR): Storing long-term design choices and technology stack justifications to maintain consistency throughout the project lifecycle.
- Configuration & Environment Optimization: Saving verified working configurations for tools, libraries, and CI/CD pipelines to streamline environment setup and dependency management.
- Session-Based Debugging: Managing temporary state and exploratory findings during a specific task to maintain high-fidelity context without cluttering permanent knowledge bases.
- Pattern Recognition & Reuse: Cataloging reusable code patterns and performance optimization techniques discovered during development for instant recall in relevant tasks.
| name | mcp-memory-management |
|---|---|
| description | Guide for using Gaia's MCP memory tools (remember/recall) with session-level and persistent storage. Use when debugging, implementing features, or making decisions. |
MCP Memory Management
Tools
mcp__gaia__remember(category, key, value, duration)- Store knowledge with optional persistencemcp__gaia__recall(query, maxResults?)- Search memories (fuzzy matching, aggregates session + persistent)
Memory Duration Types
SessionLength (Default)
- Duration: Current terminal session only
- Persistence: Lost when MCP service restarts
- Use For: Temporary context, debugging notes, session-specific state
ProjectWide
- Duration: Permanent (survives restarts)
- Persistence: Stored in
.gaia/memory.json - Use For: Long-term knowledge, architectural decisions, important patterns
Workflow
- BEFORE any task:
recall("[keywords]")- check past knowledge (searches both session + persistent) - AFTER any fix/learning:
remember(category, key, value, duration)- store it - Choose duration:
- Use
SessionLengthfor temporary/debugging context - Use
ProjectWidefor permanent knowledge that should persist
- Use
When to Use Each Duration
Use SessionLength (Default) For:
- ❌ Temporary debugging notes
- ❌ Current session state
- ❌ Work-in-progress context
- ❌ Exploratory findings that might change
- ❌ User-specific ephemeral data
Use ProjectWide For:
- ✅ Bug fixes and their root causes
- ✅ Working configurations that should be reused
- ✅ Architectural decisions
- ✅ Performance optimizations
- ✅ Library/dependency compatibility notes
- ✅ Reusable code patterns
- ✅ Environment-specific quirks
Categories
| Category | Use For | Example Key | Recommended Duration |
|---|---|---|---|
issue |
Bug fixes | "null_pointer_user" |
ProjectWide |
workaround |
Temporary solutions | "docker_arm_compat" |
ProjectWide |
config |
Working configurations | "vite_proxy_setup" |
ProjectWide |
pattern |
Reusable code patterns | "retry_logic" |
ProjectWide |
performance |
Optimizations | "db_index_user_id" |
ProjectWide |
test_fix |
Test solutions | "jest_async_timeout" |
ProjectWide |
dependency |
Library notes | "react_18_types" |
ProjectWide |
environment |
Platform quirks | "gh_actions_node20" |
ProjectWide |
decision |
Architecture choices | "rest_vs_graphql" |
ProjectWide |
debug |
Debugging context | "current_test_run" |
SessionLength |
state |
Session state | "last_api_response" |
SessionLength |
Key Naming
Use descriptive, searchable keys:
- ✅
"typescript_path_error"- searchable by "typescript", "path", "error" - ❌
"fix1"- not searchable
Examples
Session-Level Memories (Default)
// Temporary debugging context
remember("debug", "current_user_id", "user-123", "SessionLength");
// Session state
remember("state", "last_build_result", "success", "SessionLength");
// Work-in-progress notes
remember(
"debug",
"investigating_timeout",
"Occurs only on Chrome",
"SessionLength"
);
Persistent Memories
// Before debugging - searches both session AND persistent memories
recall("timeout");
recall("typescript error");
// After fixing an issue - PERSIST the solution
remember(
"issue",
"ts_module_resolution",
"Fixed by setting moduleResolution to bundler",
"ProjectWide"
);
// After failed attempt (prevents repeating mistakes) - PERSIST
remember(
"issue",
"vite_ssr_failed",
"SSR mode incompatible with this library",
"ProjectWide"
);
// After finding working config - PERSIST
remember(
"config",
"eslint_react",
"Needs plugin:react/recommended for JSX",
"ProjectWide"
);
// Performance optimization - PERSIST
remember(
"performance",
"db_query_users",
"Added index on email field, 10x speedup",
"ProjectWide"
);
// Architecture decision - PERSIST
remember(
"decision",
"auth_approach",
"Using JWT with 15min access + 7day refresh tokens",
"ProjectWide"
);
Best Practices
DO:
- ✅ Use
recall()BEFORE every task to check for past knowledge - ✅ Use
ProjectWidefor permanent knowledge (bug fixes, configs, patterns) - ✅ Use
SessionLengthfor temporary context (default behavior) - ✅ Store after EVERY fix or learning
- ✅ Store after EVERY failed attempt to prevent repeating
- ✅ Use descriptive, searchable keys
DON'T:
- ❌ Skip
recall()- always check past knowledge first - ❌ Use
ProjectWidefor temporary debugging notes - ❌ Use vague keys like "fix1" or "temp"
- ❌ Forget to document failed attempts
- ❌ Store duplicate knowledge (upserts automatically by category+key)
Technical Details
- Session Storage: In-memory ConcurrentDictionary (cleared on restart)
- Persistent Storage:
.gaia/memory.json(survives restarts) - File Safety: Semaphore-protected writes prevent locking issues
- Recall: Automatically aggregates results from both storage types
- Upsert: Category+Key uniqueness prevents duplicates