Skip to main content Home Creators forceinjection domain-driven-design-skills memory-coordination
memory-coordination Coordinates Serena MCP knowledge graph operations for Shannon Framework. Enforces standardized
entity naming (shannon/* namespace), relation creation patterns, search protocols, and observation
management. Prevents orphaned entities, naming chaos, and broken context lineage. Use when: storing
specs/waves/goals/checkpoints, querying Shannon history, managing knowledge graph structure,
ensuring cross-wave context preservation.
Jump to install Skills Marketplace Discover and explore AI skills built by the community.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Show prompt details A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/ForceInjection/domain-driven-design-skills --skill memory-coordinationThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Download Zip Downloading... More from this repository Conduct deep academic research for philosophy, neuroscience, cognitive science, and theoretical computer science (computability, complexity, AI theory, logic). Use when user asks to: research academic topics, find scholarly papers, conduct literature reviews, analyze citations, synthesize research findings, explore philosophical arguments, investigate consciousness/cognition, study computability/decidability/Turing machines, or analyze academic debates. Triggers on: 'research papers', 'literature review', 'academic sources', 'scholarly articles', 'philosophy of mind', 'computability theory', 'neuroscience studies', 'find papers on', 'what does the research say'.
Create clear action plans with steps, success criteria, and risk awareness. Use before implementing features, making changes, starting projects, or anytime you need a roadmap to success. Triggers on "plan this", "how should we approach", "what's the strategy", "steps to complete", or when facing complex multi-step work.
Add keyboard navigation to a feature using CommandRegistryService. Use when implementing keyboard shortcuts, vim-style navigation, or hotkeys for a page or component.
Related occupations SOC
Based on SOC occupation classification
name memory-coordination description Coordinates Serena MCP knowledge graph operations for Shannon Framework. Enforces standardized
entity naming (shannon/* namespace), relation creation patterns, search protocols, and observation
management. Prevents orphaned entities, naming chaos, and broken context lineage. Use when: storing
specs/waves/goals/checkpoints, querying Shannon history, managing knowledge graph structure,
ensuring cross-wave context preservation.
skill-type PROTOCOL shannon-version >=4.0.0 mcp-requirements {"required":[{"name":"serena","version":">=2.0.0","purpose":"Knowledge graph storage for Shannon context","fallback":"none","degradation":"critical"}],"recommended":[]} required-sub-skills [] optional-sub-skills [] allowed-tools Serena
Memory Coordination
Overview
Purpose : Memory Coordination is Shannon's protocol for structured Serena MCP operations. It enforces standardized entity naming (shannon/* namespace), mandatory relation creation, consistent search patterns, and proper observation management to maintain a clean, queryable knowledge graph across all waves and sessions.
When to Use :
Storing ANY Shannon artifact (spec, wave, goal, checkpoint, SITREP)
Querying Shannon history (waves, checkpoints, specs)
Creating entities for Shannon context preservation
Updating existing entities with new information
Establishing relations between Shannon entities
Searching Shannon knowledge graph
Expected Outcomes :
Standardized entity names with shannon/* namespace
Complete relational graph (no orphaned entities)
Efficient queries using consistent patterns
Cross-wave context preservation
Zero data duplication via observations
Clean knowledge graph structure
Duration : 10-30 seconds per operation
Anti-Rationalization (From Baseline Testing)
CRITICAL : Agents systematically rationalize skipping memory-coordination protocols. Below are the 6 most common rationalizations detected in baseline testing, with mandatory counters.
Rationalization 1: "Entity name seems fine"
Example : Agent creates entity named "spec_data" or "MyAnalysis" without shannon/ prefix
COUNTER :
❌ NEVER create Shannon entities without shannon/* namespace
✅ ALL Shannon entities MUST start with shannon/
✅ Use standard namespaces: shannon/specs/, shannon/waves/, shannon/goals/, shannon/checkpoints/, shannon/sitreps/
✅ If name lacks shannon/ prefix, it's WRONG
Rule : All Shannon entities have shannon/* namespace. No exceptions.
Rationalization 2: "Relations not needed for this entity"
Example : Agent creates wave entity without relating it to spec
COUNTER :
❌ NEVER create standalone Shannon entities
✅ EVERY entity has at least 1 relation (usually to parent or creator)
✅ Spec -> spawns -> Wave, Wave -> contains -> Task, Wave -> created_checkpoint -> Checkpoint
✅ Orphaned entities = broken context lineage
Rule : Create relations. Every entity connects to graph.
Rationalization 3: "Search query seems reasonable" Example : Agent searches with random queries: "wave", "Wave 1", "waves", "show waves"
❌ NEVER use free-form search queries for Shannon entities
✅ Use EXACT search patterns defined in this skill
✅ Search specs: search_nodes("shannon/specs/")
✅ Search waves: search_nodes("shannon/waves/")
✅ Consistency = efficiency
Rule : Use protocol search patterns. Not creative queries.
Rationalization 4: "Create new entity for update" Example : Agent creates "spec_002" to update "spec_001" instead of adding observations
❌ NEVER create new entity to update existing entity
✅ Use add_observations for updates
✅ Creating duplicate entities = data chaos
✅ Example: WRONG: create_entities("spec_002"), RIGHT: add_observations("spec_001", ["new info"])
Rule : Updates use add_observations, not create_entities.
Rationalization 5: "Namespace collision unlikely" Example : Agent creates "goal" entity in root namespace (not shannon/goals/)
❌ NEVER create Shannon entities in root namespace
✅ shannon/* namespace prevents collision with user project entities
✅ User might have "goal" entity for their app -> collision = corruption
✅ shannon/goals/goal_001 = isolated, safe
Rule : shannon/* namespace mandatory. Prevents collisions.
Rationalization 6: "Manual filtering faster than search" Example : Agent calls read_graph() then manually filters for waves
❌ NEVER read full graph then filter manually
✅ Use search_nodes() with namespace prefix (efficient, targeted)
✅ read_graph() loads ENTIRE graph (100-1000+ entities)
✅ search_nodes("shannon/waves/") returns only waves (5-20 entities)
✅ Manual filtering = wasted tokens + time
Rule : Use search_nodes with namespace. Never read_graph for queries.
Detection Signal
Create entity without shannon/ prefix
Skip creating relations
Use custom search query
Create new entity for update
Use root namespace
Read full graph then filter
Then you are rationalizing. Stop. Apply the protocol. Follow the rules.
When to Use
Storing Shannon artifacts : Specs, waves, goals, checkpoints, SITREPsQuerying Shannon history : "Show me all waves", "Find spec for this wave"Creating Shannon entities : Any Shannon data needs persistenceUpdating Shannon entities : Wave status change, checkpoint metadata updateEstablishing relations : Link wave to spec, checkpoint to wave, goal to specSearching Shannon graph : Find entities by namespace, type, or timestampContext preservation : Before wave transitions, session end, context limitsSITREP coordination : Storing multi-agent progress reports
Storing user project data (use user namespace, not shannon/*)
Non-Shannon workflows (generic Serena operations)
Temporary data that doesn't need persistence
Data that should be in project files instead of knowledge graph
Inputs
operation_type (string): Serena operation to perform
Options: "create", "read", "update", "search", "relate", "delete"
entity_data (object): Data for the operation
{
"type" : "spec" | "wave" | "goal" | "checkpoint" | "sitrep" | "task" ,
"data" : {
"complexity_score" : 0.68 ,
"domain_percentages" : { ...} ,
"execution_strategy" : "wave-based"
} ,
"timestamp" : "20250104_143022"
}
Optional (operation-specific):
entity_name (string): For read/update/delete operations
Example: "shannon/specs/spec_20250104_143022"
search_pattern (string): For search operations
Example: "shannon/waves/" (all waves)
Example: "shannon/checkpoints/cp_20250104" (date-filtered)
parent_entity (string): For create operations (establishes relation)
Example: "shannon/specs/spec_001" (wave's parent)
relation_type (string): For relate operations
Options: "spawns", "contains", "tracks", "created_checkpoint", "implements", "reports_on", "relates_to"
observations (array): For create/update operations
Example: ["type: spec_analysis", "created: 2025-01-04T14:30:22Z", "complexity_score: 0.68"]
Core Competencies
1. Shannon Namespace Management
Namespace Structure : shannon/specs/, shannon/waves/, shannon/goals/, shannon/checkpoints/, shannon/sitreps/Entity Naming : Standardized formats with timestamps or IDsCollision Prevention : shannon/* isolates Shannon entities from user projectQueryability : Namespace prefix enables efficient targeted searchesOrganization : Clear hierarchy (specs -> waves -> tasks -> checkpoints)
2. Entity CRUD Operations
Create : create_entities with shannon/* namespace, initial observationsRead : search_nodes or open_nodes with specific entity namesUpdate : add_observations to existing entities (NEVER create new entity)Delete : delete_entities (rare, only for cleanup or mistakes)Validation : Verify entity name format before creation
3. Relation Management
Standard Relations : spawns, contains, tracks, created_checkpoint, implements, relates_toMandatory Relations : EVERY entity connects to at least 1 other entityRelation Naming : Active voice (spec "spawns" wave, wave "contains" task)Bidirectional Context : Relations enable traversal (wave -> spec, checkpoint -> wave)Orphan Prevention : No standalone entities
4. Search Patterns
Namespace Search : search_nodes("shannon/specs/") for all specsSpecific Entity : open_nodes(["shannon/specs/spec_001"]) for exact entityPattern Matching : search_nodes("shannon/waves/wave_2025") for date-filtered wavesNever Full Graph : Avoid read_graph() except for full visualizationResult Limits : Use search efficiently, narrow queries
5. Observation Management
Initial Observations : Include type, creation_date, purpose, metadataUpdates : add_observations for new information (status, progress, notes)No Duplicates : Never create new entity to update (use observations)Structured Data : Store JSON or key-value pairs in observationsTimestamped : Include timestamp in observation content
Workflow
Step 1: Determine Entity Type Input : Data to store (spec, wave, goal, checkpoint, SITREP)
Identify entity type from data structure or user intent
If ambiguous, check context:
In spec analysis phase? -> shannon/specs/
Tracking wave progress? -> shannon/waves/
Setting goals? -> shannon/goals/
If still unclear, ASK USER: "Should I store this as spec, wave, goal, or checkpoint?"
NEVER default to root namespace or random name
Map to Shannon namespace:
Specification -> shannon/specs/
Wave -> shannon/waves/
Goal -> shannon/goals/
Checkpoint -> shannon/checkpoints/
SITREP -> shannon/sitreps/
Task -> shannon/tasks/ (usually nested under wave)
Generate timestamp (MANDATORY FORMAT):
Format: YYYYMMdd_HHmmss
Example: 20250104_143022 (2025-01-04 14:30:22)
WHY: Sortable (alphabetical = chronological), consistent, query-safe
const timestamp = new Date ().toISOString ()
.replace (/[-:]/g , '' )
.replace ('T' , '_' )
.split ('.' )[0 ];
NEVER use: ISO 8601 in name, human-readable dates, Unix timestamps
Sanitize entity name:
Replace spaces with underscores: "E-commerce / Payment" -> "E-commerce_Payment"
Remove forward slashes: "/" -> ""
Lowercase: "Gateway" -> "gateway"
Final: shannon/specs/e-commerce_payment_gateway_20250104_143022
NEVER include spaces or "/" in entity names (breaks queries)
Output : Full entity name (e.g., shannon/specs/spec_20250104_143022)
Step 2: Create Entity with Standard Format Input : Entity name, entity type, data
Structure observations as list of strings:
[
"type: [entity_type]",
"created: [ISO timestamp]",
"purpose: [description]",
"[key]: [value]",
"[serialized JSON if complex data]"
]
Call create_entities:
create_entities ({
entities : [{
name : "shannon/specs/spec_20250104_143022" ,
entityType : "Specification" ,
observations : [
"type: spec_analysis" ,
"created: 2025-01-04T14:30:22Z" ,
"complexity_score: 0.68" ,
"domain: Frontend 38%, Backend 35%, Database 27%" ,
"execution_strategy: wave-based" ,
"JSON: {...full analysis...}"
]
}]
})
Verify creation successful
Output : Entity created, entity name
Step 3: Create Mandatory Relations Input : New entity name, related entities
Identify parent or related entities:
Spec -> None (root entity)
Wave -> Spec (spawned from)
Task -> Wave (contained in)
Checkpoint -> Wave (created during)
Goal -> Spec (implements)
SITREP -> Wave (reports on)
Determine relation type (active voice) with VALIDATION:
APPROVED RELATION TYPES :
spawns (spec -> wave)
contains (wave -> task)
created_checkpoint (wave -> checkpoint)
implements (goal -> spec)
reports_on (sitrep -> wave)
tracks (goal -> wave)
relates_to (general purpose)
VALIDATION (prevent typos):
const approved = ["spawns" , "contains" , "created_checkpoint" ,
"implements" , "reports_on" , "tracks" , "relates_to" ];
if (!approved.includes (relationType)) {
throw Error (`Invalid relationType: ${relationType} . Use one of: ${approved.join(', ' )} ` );
}
Call create_relations:
For SINGLE entity :
create_relations ({
relations : [{
from : "shannon/specs/spec_001" ,
to : "shannon/waves/wave_001" ,
relationType : "spawns"
}]
})
For BULK operations (50+ entities) :
create_relations ({
relations : [
{from : "shannon/waves/wave_001" , to : "shannon/tasks/task_001" , relationType : "contains" },
{from : "shannon/waves/wave_001" , to : "shannon/tasks/task_002" , relationType : "contains" },
]
})
Verify relation created
Output : Relations established, connected graph
Step 4: Search Using Standard Patterns Input : Query intent (e.g., "find all waves", "get spec_001", "list checkpoints")
Map intent to search pattern:
"All [type]" -> search_nodes("shannon/[type]s/")
"Specific entity" -> open_nodes(["shannon/[type]s/[name]"])
"Recent [type]" -> search_nodes("shannon/[type]s/[date_pattern]")
Execute search with NAMESPACE PRECISION:
search_nodes ("shannon/waves/" )
open_nodes (["shannon/specs/spec_20250104_143022" ])
search_nodes ("shannon/checkpoints/cp_20250104" )
search_nodes ("spec_" )
search_nodes ("wave" )
search_nodes ("spec_001" )
RULE : Always use FULL shannon/* path. Never partial match.
Parse results
Output : Matching entities with observations
Step 5: Update via Observations Input : Entity name, new information
MANDATORY VERIFICATION (prevent errors):
const entity = open_nodes (["shannon/waves/wave_001" ]);
if (!entity || entity.length === 0 ) {
throw Error ("Cannot update: entity shannon/waves/wave_001 not found" );
}
If entity missing:
Create it first (if should exist)
Report error to user (if unexpected)
Structure new observations:
[
"updated: [ISO timestamp]",
"status: [new status]",
"[new_key]: [new_value]"
]
Call add_observations:
add_observations ({
observations : [{
entityName : "shannon/waves/wave_001" ,
contents : [
"updated: 2025-01-04T15:00:00Z" ,
"status: Phase 2 complete" ,
"progress: 60%" ,
"next_action: Begin Phase 3 implementation"
]
}]
})
OBSERVATION LIMITS (prevent overflow):
Maximum ~100 observations per entity (guideline)
If approaching limit, consider:
Creating checkpoint entity (snapshot current state)
Creating sub-entities (wave_001_phase2, wave_001_phase3)
Archiving old observations (delete_observations)
WHY: Large lists slow queries, hard to parse
Better: Structured sub-entities with relations
Verify update successful
Output : Entity updated with new observations
Step 6: Validate Graph Structure
Check entity naming:
All Shannon entities have shannon/* prefix? ✅
No typos in namespace (shannon/spec/ instead of shannon/specs/)? ✅
Check relations:
Every new entity has >=1 relation? ✅
Relations use active voice? ✅
No orphaned entities? ✅
Check operations:
Used add_observations for updates (not create_entities)? ✅
Used search_nodes (not read_graph) for queries? ✅
No duplicate entities? ✅
Output : Validation pass/fail, corrections if needed
MCP Integration
Required MCPs
Purpose : Shannon's primary context preservation mechanism; stores all specs, waves, goals, checkpoints in persistent knowledge graphUsage :
create_entities ({
entities : [{
name : "shannon/specs/spec_001" ,
entityType : "Specification" ,
observations : ["type: spec_analysis" , "created: 2025-01-04T14:30:22Z" ]
}]
})
create_relations ({
relations : [{
from : "shannon/specs/spec_001" ,
to : "shannon/waves/wave_001" ,
relationType : "spawns"
}]
})
const specs = search_nodes ("shannon/specs/" )
const wave = open_nodes (["shannon/waves/wave_001" ])
add_observations ({
observations : [{
entityName : "shannon/waves/wave_001" ,
contents : ["status: Phase 2 complete" , "progress: 60%" ]
}]
})
Fallback : NONE (Serena is mandatory for Shannon)Degradation : CRITICAL (Shannon cannot function without context preservation)Verification : Test with search_nodes("shannon/") - should return Shannon entities
Examples
Example 1: Store Spec Analysis Input : Spec analysis complete (complexity 0.68, Frontend 38%, Backend 35%, Database 27%)
Step 1: Determine entity type
-> Type: Specification
-> Namespace: shannon/specs/
-> Entity name: shannon/specs/spec_20250104_143022
Step 2: Create entity
-> create_entities({
entities: [{
name: "shannon/specs/spec_20250104_143022",
entityType: "Specification",
observations: [
"type: spec_analysis",
"created: 2025-01-04T14:30:22Z",
"complexity_score: 0.68",
"interpretation: Complex",
"domains: Frontend 38%, Backend 35%, Database 27%",
"execution_strategy: wave-based",
"recommended_waves: 3-7",
"recommended_agents: 8-15",
"timeline: 2-4 days",
"JSON: {\"complexity_score\":0.68,\"dimensions\":{...},\"domain_percentages\":{...}}"
]
}]
})
Step 3: Create relations
-> No parent (spec is root entity)
-> Relations will be created when waves spawn from this spec
Step 4: Verify creation
-> open_nodes(["shannon/specs/spec_20250104_143022"])
-> ✅ Entity exists with all observations
Output : Spec stored as shannon/specs/spec_20250104_143022, ready to spawn waves
Example 2: Create Wave from Spec Input : Starting Wave 1 for spec_20250104_143022
Step 1: Determine entity type
-> Type: Wave
-> Namespace: shannon/waves/
-> Entity name: shannon/waves/wave_20250104_150000
Step 2: Create entity
-> create_entities({
entities: [{
name: "shannon/waves/wave_20250104_150000",
entityType: "Wave",
observations: [
"type: wave",
"wave_number: 1",
"created: 2025-01-04T15:00:00Z",
"spec_id: shannon/specs/spec_20250104_143022",
"phase: Phase 2 - Architecture & Design",
"status: in_progress",
"agents: 8",
"start_time: 2025-01-04T15:00:00Z"
]
}]
})
Step 3: Create relations
-> Parent: shannon/specs/spec_20250104_143022
-> Relation: spec "spawns" wave
-> create_relations({
relations: [{
from: "shannon/specs/spec_20250104_143022",
to: "shannon/waves/wave_20250104_150000",
relationType: "spawns"
}]
})
Step 4: Verify
-> open_nodes(["shannon/waves/wave_20250104_150000"])
-> search_nodes("shannon/waves/") shows wave_20250104_150000
-> ✅ Wave created and linked to spec
Output : Wave 1 created, linked to spec via "spawns" relation
Example 3: Query Wave History Input : User asks "Show me all waves for current project"
Step 1: Map query to search pattern
-> Intent: All waves
-> Pattern: search_nodes("shannon/waves/")
Step 2: Execute search
-> search_nodes("shannon/waves/")
-> Returns:
- shannon/waves/wave_20250104_150000
- shannon/waves/wave_20250104_170000
- shannon/waves/wave_20250105_090000
Step 3: Fetch details (if needed)
-> open_nodes([
"shannon/waves/wave_20250104_150000",
"shannon/waves/wave_20250104_170000",
"shannon/waves/wave_20250105_090000"
])
Step 4: Parse observations
-> Wave 1: Phase 2, status: complete
-> Wave 2: Phase 3, status: complete
-> Wave 3: Phase 4, status: in_progress
Step 5: Format output
-> "Wave History:
- Wave 1 (2025-01-04 15:00): Phase 2 complete
- Wave 2 (2025-01-04 17:00): Phase 3 complete
- Wave 3 (2025-01-05 09:00): Phase 4 in progress"
Output : Complete wave history with status, fetched efficiently using namespace search
Example 4: Update Wave Status Input : Wave 1 completed Phase 2, moving to Phase 3
Step 1: Identify entity
-> Entity: shannon/waves/wave_20250104_150000
Step 2: Structure update observations
-> [
"updated: 2025-01-04T16:30:00Z",
"status: complete",
"phase_completed: Phase 2 - Architecture & Design",
"next_phase: Phase 3 - Implementation",
"deliverables: Architecture diagrams, API specs, DB schemas",
"validation_gate: ✅ Design approved, patterns established"
]
Step 3: Add observations (NOT create new entity)
-> add_observations({
observations: [{
entityName: "shannon/waves/wave_20250104_150000",
contents: [
"updated: 2025-01-04T16:30:00Z",
"status: complete",
"phase_completed: Phase 2 - Architecture & Design",
"next_phase: Phase 3 - Implementation",
"deliverables: Architecture diagrams, API specs, DB schemas",
"validation_gate: ✅ Design approved, patterns established"
]
}]
})
Step 4: Verify update
-> open_nodes(["shannon/waves/wave_20250104_150000"])
-> ✅ Entity has new observations appended
-> ✅ NO duplicate entity created
Output : Wave 1 updated with completion status, no data duplication
Example 5: Create Checkpoint with Relations Input : Create checkpoint at end of Wave 1
Step 1: Determine entity type
-> Type: Checkpoint
-> Namespace: shannon/checkpoints/
-> Entity name: shannon/checkpoints/cp_20250104_163000
Step 2: Create entity
-> create_entities({
entities: [{
name: "shannon/checkpoints/cp_20250104_163000",
entityType: "Checkpoint",
observations: [
"type: checkpoint",
"created: 2025-01-04T16:30:00Z",
"wave_id: shannon/waves/wave_20250104_150000",
"phase: Phase 2 complete",
"status: Validated",
"files: [list of checkpoint files]",
"context: Architecture design complete, moving to implementation"
]
}]
})
Step 3: Create relations
-> Parent: shannon/waves/wave_20250104_150000
-> Relation: wave "created_checkpoint" checkpoint
-> create_relations({
relations: [{
from: "shannon/waves/wave_20250104_150000",
to: "shannon/checkpoints/cp_20250104_163000",
relationType: "created_checkpoint"
}]
})
Step 4: Verify
-> open_nodes(["shannon/checkpoints/cp_20250104_163000"])
-> ✅ Checkpoint created
-> ✅ Relation exists: wave -> checkpoint
-> ✅ Can trace checkpoint -> wave -> spec lineage
Output : Checkpoint created and linked to wave, context lineage preserved
Outputs {
"operation" : "create" | "read" | "update" | "search" | "relate" | "delete" ,
"success" : true ,
"entity_name" : "shannon/specs/spec_20250104_143022" ,
"entity_type" : "Specification" ,
"observations" : [
"type: spec_analysis" ,
"created: 2025-01-04T14:30:22Z" ,
"complexity_score: 0.68" ,
"domains: Frontend 40%, Backend 35%, Database 25%"
] ,
"relations" : [
{
"from" : "shannon/specs/spec_20250104_143022" ,
"to" : "shannon/waves/wave_20250104_150000" ,
"type" : "spawns"
}
] ,
"validation" : {
"namespace_correct" : true ,
"relations_exist" : true ,
"format_valid" : true ,
"no_duplicates" : true } ,
"lineage" : {
"parent" : "shannon/specs/spec_20250104_143022" ,
"children" : [ "shannon/waves/wave_20250104_150000" ] ,
"depth" : 2
}
}
Success Criteria
✅ All Shannon entities have shannon/* namespace prefix
✅ Entity names follow standard format (shannon/[type]s/[name]_[timestamp])
✅ Every entity has at least 1 relation (no orphans)
✅ Relations use active voice (spawns, contains, tracks)
✅ Updates use add_observations (not create_entities)
✅ Searches use namespace prefix (search_nodes("shannon/specs/"))
✅ No duplicate entities (same data in multiple entities)
✅ Graph structure supports lineage queries (checkpoint -> wave -> spec)
✅ Observations structured with timestamps and key-value pairs
✅ Validation confirms all protocols followed
❌ Entity created without shannon/ prefix (namespace violation)
❌ Entity created without relations (orphaned)
❌ Relations use passive voice or unclear naming
❌ Update creates new entity instead of add_observations (duplication)
❌ Search uses read_graph() for targeted query (inefficiency)
❌ Duplicate entities exist for same data
❌ Cannot trace lineage (broken relations)
❌ Observations unstructured or missing timestamps
❌ Namespace collision with user project entities
❌ Custom entity naming breaks conventions
def validate_memory_coordination (result ):
"""Verify memory coordination followed protocols"""
entity_name = result.get("entity_name" , "" )
assert entity_name.startswith("shannon/" ), \
f"VIOLATION: Entity missing shannon/ prefix: {entity_name} "
valid_namespaces = ["shannon/specs/" , "shannon/waves/" , "shannon/goals/" ,
"shannon/checkpoints/" , "shannon/sitreps/" , "shannon/tasks/" ]
assert any (entity_name.startswith(ns) for ns in valid_namespaces), \
f"VIOLATION: Invalid namespace: {entity_name} "
if result.get("operation" ) == "create" and "specs" not in entity_name:
relations = result.get("relations" , [])
assert len (relations) >= 1 , \
"VIOLATION: Entity created without relations (orphaned)"
approved_relations = ["spawns" , "contains" , "created_checkpoint" ,
"implements" , "reports_on" , "tracks" , "relates_to" ]
for relation in result.get("relations" , []):
assert relation["type" ] in approved_relations, \
f"VIOLATION: Invalid relation type: {relation['type' ]} "
observations = result.get("observations" , [])
has_timestamp = any ("created:" in obs or "updated:" in obs for obs in observations)
assert has_timestamp, \
"VIOLATION: Observations missing timestamp"
validation = result.get("validation" , {})
assert validation.get("no_duplicates" ) == True , \
"VIOLATION: Duplicate entities detected"
lineage = result.get("lineage" , {})
if "specs" not in entity_name:
assert lineage.get("parent" ) is not None , \
"VIOLATION: Cannot trace lineage (broken relations)"
return True
Common Pitfalls
Pitfall 1: Missing shannon/ Prefix Problem : Agent creates "spec_001" instead of "shannon/specs/spec_001"
Namespace collision with user project entities (user might have "spec_001" entity)
Cannot query all Shannon entities efficiently (search_nodes("shannon/") fails)
Breaks Shannon isolation from project
Solution : ALWAYS prefix with shannon/[type]s/ (specs, waves, goals, checkpoints, sitreps)
Prevention : Validation rejects entities without shannon/ prefix
Pitfall 2: Orphaned Entities Problem : Agent creates wave entity but forgets to link to parent spec
Cannot trace wave -> spec lineage
Cannot answer "which spec spawned this wave?"
Context restoration impossible
Solution : EVERY entity MUST have >=1 relation (except root specs)
Prevention : Step 3 mandatory relation creation, validation checks
Pitfall 3: Update Creates Duplicate Problem : Agent creates "spec_002" to update "spec_001" instead of adding observations
Data duplication (two entities with overlapping information)
Queries return multiple results (which is correct?)
Graph pollution
Solution : Use add_observations for updates, NOT create_entities
Prevention : Skill emphasizes update protocol, anti-rationalization section
Pitfall 4: Inefficient Search Problem : Agent calls read_graph() then manually filters for waves
Loads entire graph (100-1000+ entities) when only need 5-20 waves
Wastes tokens and time
Unnecessary network traffic
Solution : Use search_nodes("shannon/waves/") for targeted query
Prevention : Step 4 search patterns, avoid read_graph() for queries
Pitfall 5: Inconsistent Entity Naming Problem : Agent creates shannon/specs/spec_001, shannon/specs/specification_002, shannon/specs/my_spec_3
Inconsistent patterns hard to query (search_nodes("shannon/specs/spec_") misses "specification_")
Breaks naming conventions
Confusion about entity type
Solution : Standardize: shannon/specs/spec_[timestamp] or shannon/specs/spec_[id]
Prevention : Step 1 entity naming protocol, examples show standard format
Pitfall 6: Missing Timestamps Problem : Agent creates observations without timestamps (["status: complete", "progress: 100%"])
Cannot determine WHEN update happened
Cannot trace progress timeline
Loses historical context
Solution : ALWAYS include timestamp in observations: ["updated: 2025-01-04T16:30:00Z", "status: complete"]
Prevention : Step 2 and Step 5 observation format includes timestamps
Validation How to verify memory-coordination executed correctly :
Check Entity Names :
search_nodes("shannon/") returns only Shannon entities ✅
All entity names have shannon/[type]s/ prefix ✅
No entities in root namespace with Shannon data ✅
Check Relations :
Query entity -> Verify >=1 relation exists ✅
Relations use active voice (spawns, contains, tracks) ✅
Can trace lineage: checkpoint -> wave -> spec ✅
Check Operations :
Updates used add_observations (not create_entities) ✅
No duplicate entities (same data in multiple entities) ✅
Searches used namespace prefix (not read_graph()) ✅
Check Observations :
All observations have timestamps ✅
Observations structured as key-value or JSON ✅
Latest observations at end of list ✅
Test Queries :
search_nodes("shannon/specs/") returns only specs ✅
search_nodes("shannon/waves/") returns only waves ✅
open_nodes(["shannon/specs/spec_001"]) returns specific spec ✅
Queries execute in <2 seconds ✅
Test Lineage :
Given checkpoint -> Can find parent wave ✅
Given wave -> Can find parent spec ✅
Given wave -> Can find all child tasks ✅
Given spec -> Can find all spawned waves ✅
Progressive Disclosure SKILL.md (This file): ~600 lines
Overview, when to use, expected outcomes
Anti-rationalization (6 violations with counters)
5 core competencies (namespace, CRUD, relations, search, observations)
6-step workflow (determine type, create, relate, search, update, validate)
5 examples (store spec, create wave, query history, update status, checkpoint)
Success criteria, common pitfalls, validation
references/ : No deep references needed (protocol is self-contained)
Claude loads references/ when : N/A (all protocol details in SKILL.md)
References
Serena MCP documentation: https://github.com/cyanheads/serena-mcp
Shannon context management: shannon-plugin/core/CONTEXT_MANAGEMENT.md
Checkpoint protocols: shannon-plugin/skills/context-preservation/SKILL.md
Wave orchestration: shannon-plugin/skills/wave-orchestration/SKILL.md
Metadata Version : 4.0.0
Last Updated : 2025-11-04
Author : Shannon Framework Team
License : MIT
Status : Core (Protocol skill, mandatory for Serena MCP operations)
