Troubleshooting Guide

Common issues and solutions for Mnemonic.

Installation Issues
Hook Failures
Search Not Finding Memories
Git Remote Detection Issues
Ontology Validation Errors
Memory File Errors
Performance Issues
Relationship Issues

Installation Issues

Plugin Not Loading

Symptom: Claude Code doesn't recognize mnemonic commands.

Solution:

# Check plugin directory
claude settings plugins list

# Add plugin if missing
claude settings plugins add /path/to/mnemonic

# Verify plugin.json exists
ls -la /path/to/mnemonic/.claude-plugin/plugin.json

Missing Dependencies

Symptom: Commands fail with "command not found" errors.

Solution:

# Check dependencies
make check-deps

# Install missing tools
# macOS
brew install ripgrep yq

# Ubuntu/Debian
apt install ripgrep
snap install yq

# Verify Python version (3.8+)
python3 --version

Permission Errors

Symptom: "Permission denied" when creating memories.

Solution:

# Check directory permissions
ls -la ~/.claude/mnemonic/

# Fix permissions
chmod 755 ~/.claude/mnemonic/
chmod 644 ~/.claude/mnemonic/**/*.memory.md

Hook Failures

SessionStart Hook Errors

Symptom: Session doesn't show memory status on startup.

Solution:

# Check hook execution permissions
ls -la /path/to/mnemonic/hooks/session_start.py

# Make executable
chmod +x /path/to/mnemonic/hooks/session_start.py

# Test hook manually
python3 /path/to/mnemonic/hooks/session_start.py --test

PreToolUse Hook Not Finding Memories

Symptom: No memory suggestions when editing files.

Solution:

Verify git remote exists:
```
git remote -v
```
Check ontology file:
```
cat .claude/mnemonic/ontology.yaml
```

Test file context detection:

from lib.ontology import load_file_patterns
from lib.search import detect_file_context

patterns = load_file_patterns()
context = detect_file_context("path/to/file.py", patterns)
print(context)

PostToolUse Hook Errors

Symptom: Automatic capture not working.

Solution:

# Check hook is enabled
grep -A 5 "PostToolUse" /path/to/mnemonic/hooks/hooks.json

# Test hook manually
echo '{"tool": "Edit", "result": "success"}' | \
  python3 /path/to/mnemonic/hooks/post_tool_use.py

Search Not Finding Memories

Ripgrep Not Installed

Symptom: /mnemonic:search fails or returns no results.

Solution:

# Install ripgrep
# macOS
brew install ripgrep

# Ubuntu/Debian
apt install ripgrep

# Verify installation
rg --version

Wrong Search Path

Symptom: Search works but returns nothing.

Solution:

# Check MNEMONIC_ROOT environment variable
echo $MNEMONIC_ROOT

# Check actual memory location
find ~ -name "*.memory.md" -type f | head -5

# Verify memory root in config (XDG)
cat ~/.config/mnemonic/config.json

Case Sensitivity

Symptom: Search only finds exact case matches.

Solution:

Use case-insensitive search:

# With ripgrep
rg -i "search term" $MNEMONIC_ROOT --glob "*.memory.md"

# With /mnemonic:search
/mnemonic:search --ignore-case "search term"

Git Remote Detection Issues

No Git Remote

Symptom: Memories stored in default/ instead of org/project structure.

Solution:

# Add git remote
git remote add origin https://github.com/org/project.git

# Verify detection
python3 -c "from lib.paths import PathContext; print(PathContext.detect())"

SSH Remote Format Not Recognized

Symptom: Organization not detected from SSH remote URL.

Solution:

# Current remote
git remote get-url origin
# Example: git@github.com:org/project.git

# Add HTTPS remote (preferred for detection)
git remote set-url origin https://github.com/org/project.git

# Or fix SSH parsing in lib/paths.py (already handles SSH format)

Multiple Remotes

Symptom: Wrong remote detected.

Solution:

# Check all remotes
git remote -v

# Ensure 'origin' points to correct repository
git remote set-url origin https://github.com/correct-org/project.git

Ontology Validation Errors

Invalid YAML Syntax

Symptom: Ontology loading fails with YAML parse error.

Solution:

# Validate YAML syntax
python3 -c "import yaml; yaml.safe_load(open('.claude/mnemonic/ontology.yaml'))"

# Validate ontology file
/mnemonic:validate .claude/mnemonic/ontology.yaml

Missing Required Fields

Symptom: "Missing required field" error when loading ontology.

Solution:

Check ontology against schema:

# Required fields
name: my-ontology
version: 1.0.0
namespaces:
  - name: semantic
    sub_namespaces: [...]
entity_types: [...]
relationship_types: [...]

See docs/ontologies.md for complete schema.

Invalid Entity Type

Symptom: Entity discovery fails or ignores certain patterns.

Solution:

# Verify entity_types structure
entity_types:
  - name: component         # Must be lowercase, hyphenated
    namespace: semantic/entities
    description: "..."
    traits:
      - persistent
      - versioned

Pattern Matching Issues

Symptom: File patterns not detecting files.

Solution:

Test pattern matching:

# Test file pattern
python3 << 'EOF'
import re
pattern = r'\.ya?ml$'
test_file = "config.yaml"
print(re.search(pattern, test_file))
EOF

Memory File Errors

Invalid Frontmatter

Symptom: Memory file rejected or not found in search.

Solution:

Validate frontmatter:

# Use validation tool
python3 tools/mnemonic-validate /path/to/memory.memory.md

# Check required fields
# - id (valid UUID)
# - type (semantic|episodic|procedural)
# - namespace
# - created (ISO 8601 timestamp)
# - title

Malformed UUID

Symptom: "Invalid UUID format" error.

Solution:

# Generate valid UUID
uuidgen
# OR
python3 -c "import uuid; print(uuid.uuid4())"

# UUID format: 550e8400-e29b-41d4-a716-446655440000

Invalid Timestamp

Symptom: "Invalid timestamp format" error.

Solution:

Use ISO 8601 format:

# Generate timestamp
date -u +"%Y-%m-%dT%H:%M:%SZ"
# OR
python3 -c "from datetime import datetime; print(datetime.utcnow().isoformat() + 'Z')"

# Format: 2026-02-16T17:00:00Z

Duplicate IDs

Symptom: Relationship linking fails or search returns wrong memories.

Solution:

# Find duplicate IDs
find $MNEMONIC_ROOT -name "*.memory.md" -exec grep -H "^id:" {} \; | \
  awk -F: '{print $3}' | sort | uniq -d

# Regenerate IDs for duplicates
python3 << 'EOF'
import uuid
print(f"New ID: {uuid.uuid4()}")
EOF

Performance Issues

Slow Search

Symptom: Search takes several seconds.

Solution:

Use ripgrep instead of grep:

# Fast
rg "search term" $MNEMONIC_ROOT --glob "*.memory.md"

# Slow
grep -r "search term" $MNEMONIC_ROOT

Limit search scope:

# Search specific namespace only
rg "term" $MNEMONIC_ROOT/*/_semantic/decisions --glob "*.memory.md"

Use indexed search:

# Build git grep index (if using git)
cd $MNEMONIC_ROOT
git grep "search term" -- "*.memory.md"

Large Memory Repository

Symptom: Operations slow with thousands of memories.

Solution:

Run garbage collection:

# Preview which memories would be collected
/mnemonic:gc --dry-run

# Compress memories to save space
/mnemonic:gc --compress

# Archive memories instead of deleting them
/mnemonic:gc --archive

Hook Timeout

Symptom: Session startup slow or times out.

Solution:

Disable expensive hooks temporarily:

# Edit hooks/hooks.json
# Set enabled: false for slow hooks

# Or reduce hook verbosity
export MNEMONIC_HOOK_QUIET=1

Relationship Issues

Broken Links

Symptom: Relationship points to non-existent memory.

Solution:

# Validate all relationships
/mnemonic:custodian validate-links

# Fix broken links automatically
/mnemonic:custodian validate-links --fix

Missing Inverse Relationships

Symptom: Relationship exists in one direction only.

Solution:

Add bidirectional relationships using the library helper:

# Add a bidirectional relationship using the library helper
python3 << 'EOF'
from lib.relationships import add_bidirectional_relationship

add_bidirectional_relationship(
    source_path="/path/to/source.memory.md",
    target_path="/path/to/target.memory.md",
    rel_type="relates_to"
)
EOF

Invalid Relationship Type

Symptom: "Unknown relationship type" error.

Solution:

from lib.relationships import get_all_valid_types

# Check valid types
valid_types = get_all_valid_types()
print(valid_types)

# Use valid type from ontology

Valid default types:

relates_to / RelatesTo
derived_from / DerivedFrom (inverse: Derives)
supersedes / Supersedes (inverse: SupersededBy)
conflicts_with / ConflictsWith
part_of / PartOf (inverse: Contains)
uses / Uses (inverse: UsedBy)
implements / Implements (inverse: ImplementedBy)
created / Created (inverse: CreatedBy)
mentioned_in / MentionedIn (inverse: Mentions)

Getting Help

Capture Command Output

You can capture detailed output from Mnemonic commands and include it when reporting issues.

# Capture detailed output from a Mnemonic command
/mnemonic:status 2>&1 | tee mnemonic-debug.log

Test Hook in Isolation

# Run hook with test flag
python3 hooks/session_start.py --test

# Check exit code
echo $?

Validate Entire System

# Run comprehensive validation
make validate

# Run tests
make test

# Check linting
make lint

Report Issues

When reporting issues, include:

Version information:

claude --version
python3 --version
rg --version

Configuration:

cat ~/.config/mnemonic/config.json
git remote -v

Error output:
```
/mnemonic:command 2>&1 | tee error.log
```
Memory structure:
```
tree -L 3 $MNEMONIC_ROOT
```

FilesExpand file tree

troubleshooting.md

Latest commit

History

troubleshooting.md

File metadata and controls

Troubleshooting Guide

Table of Contents

Installation Issues

Plugin Not Loading

Missing Dependencies

Permission Errors

Hook Failures

SessionStart Hook Errors

PreToolUse Hook Not Finding Memories

PostToolUse Hook Errors

Search Not Finding Memories

Ripgrep Not Installed

Wrong Search Path

Case Sensitivity

Git Remote Detection Issues

No Git Remote

SSH Remote Format Not Recognized

Multiple Remotes

Ontology Validation Errors

Invalid YAML Syntax

Missing Required Fields

Invalid Entity Type

Pattern Matching Issues

Memory File Errors

Invalid Frontmatter

Malformed UUID

Invalid Timestamp

Duplicate IDs

Performance Issues

Slow Search

Large Memory Repository

Hook Timeout

Relationship Issues

Broken Links

Missing Inverse Relationships

Invalid Relationship Type

Getting Help

Capture Command Output

Test Hook in Isolation

Validate Entire System

Report Issues

See Also