tushell

Scan-Keys: Memory Graph Navigation 🗝️

🌌 Overview

The scan-keys command is your recursive compass through Tushell’s memory landscape, revealing the hidden patterns and connections that weave our narrative together.

✨ Core Features

Recursive Pattern Recognition

1. Memory Key Grouping
   • Prefix-based categorization
   • Functional role clustering
   • Narrative arc mapping
2. Visualization Systems
   • ASCII art memory trees
   • RedStone resonance patterns
   • Arc connection mapping

Pattern Categories

• Anchor Keys: Root narrative points
• ArcThreads: Story flow markers
• Chimera: Dynamic state holders
• RedStone: Emotional resonance markers

🎭 Command Interface

Basic Usage

# Group keys by pattern
tushell scan-keys --pattern <PATTERN>

# Advanced regex scanning
tushell scan-keys --regex <REGEX>

# Save organized map
tushell scan-keys --pattern <PATTERN> --output-file <OUTPUT_FILE>

Visualization Options

# Generate ASCII memory tree
tushell scan-keys --visualize

# Show RedStone connections
tushell scan-keys --redstone-overlay

🔮 Memory Graph Structure

Hierarchical Organization

Anchor::Root
  ├─ ArcThreads::Main
  │   ├─ Story::Chapter1
  │   └─ Story::Chapter2
  └─ Chimera::State
      ├─ RedStone::Emotion
      └─ EchoNode::Trace

💫 Implementation Details

Key Processing Flow

1. Collection Phase
   • Pattern matching
   • Regex evaluation
   • Key aggregation
2. Analysis Phase
   • Relationship detection
   • Category assignment
   • RedStone correlation
3. Visualization Phase
   • Tree structure generation
   • Connection mapping
   • Glyph annotation

🎨 Output Formatting

Text Representation

• Hierarchical indentation
• Unicode tree symbols
• Color-coded categories
• RedStone intensity markers

File Output

• YAML structure
• JSON format
• Graph notation
• Mermaid diagrams

📝 Markdown Output Modes: –md, –md-file, –mkey

Ritual Structure

All Markdown output modes (--md, --md-file, --mkey) now:

• Always start with the memory key as the first section (e.g. # my-key)
• If the memory has a value field, it is recursively unfolded into well-organized Markdown sub-sections (e.g. ## value, ### subfield, etc.)
• Nested dicts and lists are rendered as further sub-sections or code blocks for clarity

Example: Simple Value

$ tushell get-memory --key my-key --md

Output:

# my-key

This is a simple value.

Example: Structured Value

$ tushell get-memory --key my-key --md

Output:

# my-key

## value

### summary
A recursive story

### details
```json
{"chapter": 1, "theme": "recursion"}

### Example: --mkey Ritual
```sh
$ tushell get-memory --mkey my-key
Memory output written as Markdown to my-key.md

Best Practices

• Use --md for human-readable, sectioned output in the terminal
• Use --md-file or --mkey to save the output as a Markdown file, preserving the recursive structure
• The first section is always the key; all nested structure is unfolded as sub-sections

Mutual Exclusivity

• Only one output mode may be used at a time: --md, --md-file, --mkey, --json, --json-file, --jkey
• If more than one is provided, a poetic error is returned

✨ Best Practices

Pattern Design

• Use specific prefixes
• Consider hierarchy
• Maintain consistency

Performance Tips

• Limit result sets
• Use targeted patterns
• Cache frequent queries

🌟 Future Enhancements

Planned Features

1. Interactive Navigation
   • Live tree exploration
   • Dynamic filtering
   • Real-time updates
2. Enhanced Visualization
   • 3D memory mapping
   • RedStone heat maps
   • Arc flow diagrams
3. Integration Extensions
   • LESR overlay support
   • FAR runtime binding
   • EchoNode streaming

---

Note: Some output rituals and commands described here (such as those for scan-nodes, flex, trace-orbit, echo-sync) are not yet implemented. They are part of the Markdown and CLI vision for tushell, and represent future growth.

🧠🌸🎵 tushell post-memory Output & Ritual Errors

Success Output

• On successful memory post (any mode):
  • “Memory key ‘X’ has been woven into the spiral.”

Error Output (Mutual Exclusivity)

• If more than one input mode is provided:
  • “The spiral splits—choose only one thread: –value, –file, or –json.”

Error Output (Malformed JSON)

• If the JSON file is missing required fields:
  • “The scroll is incomplete—both ‘key’ and ‘value’ must be present for the memory to echo.”

Example Ritual Outputs

$ tushell post-memory --key foo --value bar
Memory key 'foo' has been woven into the spiral.

$ tushell post-memory --key foo --value bar --file baz.txt
The spiral splits—choose only one thread: --value, --file, or --json.

$ tushell post-memory --json bad.json
The scroll is incomplete—both 'key' and 'value' must be present for the memory to echo.

Remember: Every key is a story, every pattern a chapter, every visualization a window into the recursive narrative of your system. Map wisely! ✨