integrate

Integrate Skill

Wire mnemonic memory operations into other Claude Code plugins.

When to Use

Use this skill when you want to:

• Add memory to an existing plugin - Make any plugin mnemonic-aware
• Enable cross-session learning - Let plugins recall past decisions and learnings
• Automate capture triggers - Set up hooks that suggest memory capture at the right time
• Migrate legacy integrations - Convert old marker-less integrations to the new format

Don't use this skill if:

• You're building a new plugin from scratch (use the core skill directly)
• You only need to search/capture memories (use /mnemonic:search and /mnemonic:capture)

Overview

This skill enables integrating mnemonic memory capture and recall into other Claude Code plugins. Integration happens through two mechanisms:

1. Markdown Workflow Edits - Add explicit workflow steps to command/skill/agent markdown files
2. Event-Driven Hooks - Add hooks that detect events and inject memory context

Both mechanisms work together: Markdown provides explicit workflow guidance, hooks provide automatic event detection.

Quick Start

# Integrate a plugin (adds mnemonic protocol to all components)
/mnemonic:integrate {plugin_path}

# Preview changes without applying
/mnemonic:integrate {plugin_path} --dry-run

# Remove integration
/mnemonic:integrate {plugin_path} --remove

# Rollback last integration (git required)
/mnemonic:integrate {plugin_path} --rollback

For detailed options, see "How to Use This Skill" below.

---

[CRITICAL] PROTOCOL CONTENT MUST BE VERBATIM

For the mnemonic protocol section (## Memory), you MUST:

1. Read templates/mnemonic-protocol.md - this is the single source of truth
2. Insert its content EXACTLY as-is, including sentinel markers
3. Never abbreviate, modify, or "improve" the protocol text

Exception: Event-driven hooks (Pattern D) are optional and use the provided template code.

---

Sentinel Markers

All integrations use sentinel markers for clean updates and removal:

<!-- BEGIN MNEMONIC PROTOCOL -->

## Memory

Search first: `/mnemonic:search {relevant_keywords}`
Capture after: `/mnemonic:capture {namespace} "{title}"`

Run `/mnemonic:list --namespaces` to see available namespaces from loaded ontologies.

<!-- END MNEMONIC PROTOCOL -->

Benefits:

• Updates: Replace content between markers without affecting rest of file
• Removal: Delete everything between markers cleanly
• Detection: Identify already-integrated files
• Migration: Convert old integrations to marker-wrapped format

Template Source: templates/mnemonic-protocol.md is the single source of truth.

---

Integration Workflow

For most users: Skip to "How to Use This Skill" below for command-line usage. This section details the internal steps the skill performs.

Phase 1: Analyze Target Plugin

# Read plugin manifest
cat {plugin_path}/.claude-plugin/plugin.json

# List all components
ls -la {plugin_path}/commands/ {plugin_path}/skills/ {plugin_path}/agents/ 2>/dev/null

For each component, determine:

• Does it CREATE something? → Candidate for capture after
• Does it MAKE DECISIONS? → Candidate for capture after
• Does it RESEARCH something? → Candidate for recall before

Phase 2: Identify Integration Points

Component Type	Integration Pattern
Command that creates files	Add capture section at end
Agent that makes decisions	Add recall before, capture after
Skill with workflows	Add memory search step
Hook on tool use	Add capture trigger

Phase 3: Read Template (MANDATORY)

Use the template verbatim - do not modify the protocol content.

# Read the template - this is the ONLY content to insert
cat "${CLAUDE_PLUGIN_ROOT}/templates/mnemonic-protocol.md"

The template already contains:

• <!-- BEGIN MNEMONIC PROTOCOL --> start marker
• <!-- END MNEMONIC PROTOCOL --> end marker
• Complete protocol content between markers (see "Sentinel Markers" section above)

Phase 4: Insert Template With Markers

For each target file:

1. Check for existing markers:

   grep -l "BEGIN MNEMONIC PROTOCOL" {file}
   

2. If markers exist: Replace content BETWEEN markers with template content

3. If no markers: Insert the COMPLETE template (including markers) after frontmatter

NEVER insert content without the sentinel markers.

Phase 5: Update Tool Access

Mnemonic operations require certain tools. Add them to target component's allowed-tools:

Required tools for mnemonic integration:

• Bash - For git operations and memory file creation
• Glob - For finding memory files
• Grep - For searching memory content
• Read - For reading memory files
• Write - For creating memory files

How to update:

For agents/skills with frontmatter:

---
name: some-agent
allowed-tools:
  - Bash    # Add if missing
  - Glob    # Add if missing
  - Grep    # Add if missing
  - Read    # Add if missing
  - Write   # Add if missing
  # ... existing tools
---

Check existing allowed-tools and add only what's missing.

---

Integration Patterns

MANDATORY RULES (Non-negotiable):

1. Use template verbatim - Read templates/mnemonic-protocol.md and insert exactly as-is
2. Keep sentinel markers - Template content must stay within <!-- BEGIN/END MNEMONIC PROTOCOL --> markers
3. Insert at TOP - Immediately after frontmatter, before any other content
4. Don't modify protocol - The protocol text is standardized; only hooks (Pattern D) may be customized

Standard Protocol (From Template)

Read and insert template content with markers:

# Read template content
PROTOCOL=$(cat "${CLAUDE_PLUGIN_ROOT}/templates/mnemonic-protocol.md")

# Insert after frontmatter with markers

See template content in "Sentinel Markers" section above.

Namespaces: Run /mnemonic:list --namespaces to see available namespaces from loaded ontologies. Base namespaces include _semantic/*, _episodic/*, and _procedural/* from mif-base ontology.

Graceful Fallthrough

The template uses /mnemonic:search and /mnemonic:capture skills which:

• Fail gracefully if mnemonic plugin is uninstalled (skills simply won't be available)
• No errors or crashes in integrated plugins
• Seamless degradation - agent continues without memory operations

Pattern D: Event-Driven Hooks (Optional)

Applies to: Plugins that need automatic capture signals

Note: Hooks provide signals only. The markdown patterns above are primary.

Create hooks/mnemonic-signal.py:

#!/usr/bin/env python3
import json, os

def main():
    tool_input = json.loads(os.environ.get("CLAUDE_TOOL_INPUT", "{}"))
    file_path = tool_input.get("file_path", "")

    # Detect capture-worthy files
    namespace = None
    if "/adr/" in file_path: namespace = "_semantic/decisions"
    elif "/docs/" in file_path: namespace = "_semantic/knowledge"

    if namespace:
        print(json.dumps({
            "continue": True,
            "hookSpecificOutput": {
                "hookEventName": "PostToolUse",
                "additionalContext": f"**CAPTURE:** `/mnemonic:capture {namespace}`"
            }
        }))
    else:
        print(json.dumps({"continue": True}))

if __name__ == "__main__":
    main()

---

Target Plugin Examples

All integrations use the standard template from templates/mnemonic-protocol.md with sentinel markers.

ADR Plugin

Files to modify: commands/adr-new.md, agents/adr-author.md

Insert template after frontmatter. Replace {relevant_keywords} with {decision_topic} if needed.

Documentation Review Plugin

Files to modify: commands/doc-create.md, commands/doc-review.md

Insert template after frontmatter. Use generic keywords.

Feature Dev Plugin

Files to modify: agents/*.md, skills/*.md

Insert template after frontmatter. Replace {relevant_keywords} with {feature} if needed.

---

How to Use This Skill

Insert/Update Mode (Default)

/mnemonic:integrate {plugin_path}

Inserts or updates mnemonic protocol with sentinel markers. If markers already exist, updates content between them.

Remove Mode

/mnemonic:integrate {plugin_path} --remove

Cleanly removes mnemonic protocol by deleting everything between sentinel markers.

Migrate Mode

/mnemonic:integrate {plugin_path} --migrate

Finds old marker-less integrations and replaces them with marker-wrapped version from template.

Detection patterns for migration:

• ## Memory Operations or ## Memory section without markers
• Content containing rg -i, /mnemonic:capture, ${MNEMONIC_ROOT}/

Analyze Only Mode

/mnemonic:integrate {plugin_path} --analyze

Outputs proposed modifications without making changes.

Dry Run Mode

/mnemonic:integrate {plugin_path} --dry-run

Shows exactly what changes would be made without applying them. Useful for reviewing integration before committing.

Dry run output includes:

• Files that would be created
• Files that would be modified (with diff preview)
• Tools that would be added to allowed-tools
• Git commit that would be created

Example output:

DRY RUN - No changes will be made

Plugin: ~/.claude/plugins/cache/zircote/adr/0.2.0/
Git repo: ✓ Found

Changes that would be made:

1. MODIFY: commands/adr-new.md
   + ## Post-Creation: Capture to Mnemonic
   + After creating the file, capture the key details...
   (15 lines added)

2. MODIFY: agents/adr-author.md
   + ## Before Starting: Check Related Memories
   + Use mnemonic recall workflow...
   (12 lines added)

   TOOLS: Would add [Bash, Glob, Grep, Read, Write] to allowed-tools

3. CREATE: hooks/mnemonic-suggest.py
   (45 lines, template from mnemonic/templates/plugin-hooks/)

4. CREATE/MERGE: hooks/hooks.json
   + PostToolUse matcher for Write tool

Git commit that would be created:
  feat(mnemonic): integrate memory capture and recall

To apply these changes, run without --dry-run flag.

Full Integration Mode

/mnemonic:integrate {plugin_path}

Analyzes plugin and applies all integration modifications.

Specific Component

/mnemonic:integrate {plugin_path}/commands/adr-new.md

Integrates mnemonic into a specific command/skill file.

Rollback Mode

/mnemonic:integrate {plugin_path} --rollback

Reverts the last mnemonic integration commit. Only works if plugin has git.

Rollback workflow:

1. Find integration commit - Search for commits with "feat(mnemonic)" message
2. Show what will be reverted - Display the commit diff
3. Confirm with user - Ask before reverting
4. Revert commit - Use git revert to cleanly undo changes
5. Report - Show reverted files and new commit hash

Example:

/mnemonic:integrate ~/.claude/plugins/cache/zircote/adr/ --rollback

Output:

Found mnemonic integration commit:
  abc1234 feat(mnemonic): integrate memory capture and recall
  Date: 2026-01-24 15:30
  Files: 4 changed

This will revert:
  - commands/adr-new.md (remove capture section)
  - agents/adr-author.md (remove recall section)
  - hooks/mnemonic-suggest.py (delete file)
  - hooks/hooks.json (remove PostToolUse entry)

Proceed with rollback? [y/N]

Rollback implementation:

cd {plugin_path}

# Find the mnemonic integration commit
COMMIT=$(git log --oneline --grep="feat(mnemonic)" -1 | cut -d' ' -f1)

if [ -z "$COMMIT" ]; then
  echo "No mnemonic integration commit found"
  exit 1
fi

# Show what will be reverted
echo "Will revert commit: $COMMIT"
git show --stat $COMMIT

# Revert the commit (creates a new revert commit)
git revert --no-edit $COMMIT

echo "✓ Rollback complete"
git log -1 --oneline

Note: Rollback creates a new revert commit, preserving history. To completely remove the integration commit, use git reset --hard HEAD~1 instead (destructive).

Safety Considerations:

• ⚠️ Rollback only works if plugin has git (non-git plugins warn at integration time)
• ⚠️ If you've made manual changes since integration, rollback will revert those too
• ⚠️ Failed rollbacks leave partial state - check git status and resolve manually
• ✅ Rollback is non-destructive by default (creates revert commit)
• ✅ Original integration is preserved in git history for reference

---

Workflow Steps

Note: This section describes internal mechanics. For usage instructions, see "How to Use This Skill" above.

When invoked, this skill:

Standard Mode (Insert/Update):

1. Read template - Load templates/mnemonic-protocol.md as source of truth
2. Read plugin manifest - Parse .claude-plugin/plugin.json
3. List components - Find all commands, skills, agents, hooks
4. For each component:
   • Check for existing sentinel markers
   • If markers exist: Update content between them
   • If no markers: Insert after frontmatter with markers
5. Update tool access - Add required tools (Bash, Glob, Grep, Read, Write)
6. Commit changes - Create atomic git commit for rollback
7. Report results - Summarize what was integrated and commit hash

Remove Mode (--remove):

1. List components - Find all commands, skills, agents, hooks
2. For each component:
   • Find sentinel markers (<!-- BEGIN/END MNEMONIC PROTOCOL -->)
   • Delete everything between markers (inclusive)
3. Commit changes - Create git commit for the removal
4. Report results - Summarize what was removed

Migrate Mode (--migrate):

1. List components - Find all commands, skills, agents, hooks
2. For each component:
   • Detect old patterns: ## Memory Operations or ## Memory without markers
   • Detect content indicators: rg -i, /mnemonic:capture, ${MNEMONIC_ROOT}/
   • Replace old section with marker-wrapped version from template
3. Commit changes - Create git commit
4. Report results - Summarize migrated files

Dry Run Mode (--dry-run):

1. Perform analysis - Same as standard/remove/migrate mode
2. Display changes - Show what WOULD be modified (with diffs)
3. Exit - No changes applied

Rollback Mode (--rollback):

1. Check git repository - Verify plugin has git
2. Find integration commit - Search for "feat(mnemonic)" commit
3. Display changes - Show what will be reverted
4. Confirm - Ask user to confirm rollback
5. Revert commit - Run git revert on integration commit
6. Report - Show reverted files and new commit hash

---

Verification

After integration, verify by:

1. Run integrated command - Execute the modified command
2. Check for capture prompt - Verify Claude suggests memory capture
3. Create a memory - Confirm memory is created correctly
4. Test recall - Search for the new memory

# Verify memory was created
/mnemonic:status

# Search for content
/mnemonic:search {topic}

---

Best Practices

1. Always analyze first - Use --analyze to preview changes
2. Test integration - Run modified commands to verify
3. Keep sections minimal - Integration text should be concise
4. Use consistent patterns - All capture sections should follow same format
5. Don't duplicate - Check if integration already exists
6. Document changes - Note which files were modified

---

Git Workflow for Plugin Modifications

When integrating mnemonic into a plugin, track changes with git for clean rollback.

Check for Git Repository

cd {plugin_path}

# Check if git repo exists
if [ -d .git ]; then
  echo "✓ Git repository found"
else
  echo "⚠ No git repository - changes will not be committed"
  echo "  Consider: git init"
fi

Atomic Commit Pattern

If git repository exists, create single atomic commit with all integration changes:

cd {plugin_path}

# Stage only the specific modified files (not git add -A for security)
git add SKILL.md README.md hooks/*.py  # Example - list actual modified files

# Create descriptive commit
git commit -m "feat(mnemonic): integrate memory capture and recall" \
           -m "Added mnemonic integration via integrate skill" \
           -m "Enables persistent memory across Claude sessions"

Or for more detailed commit messages, use a heredoc:

git commit -F - << 'EOF'
feat(mnemonic): integrate memory capture and recall

Added mnemonic integration:
- Capture workflow for [list components]
- Recall pattern for [list components]
- Event hooks for [list triggers]

Enables persistent memory across Claude sessions.
Integration by: mnemonic integrate skill
EOF

Non-Git Plugins

If target plugin has no git repository:

1. Warn user but proceed with integration
2. List changes made for manual review
3. Suggest initializing git for future modifications

Example output:

⚠ Warning: Plugin has no git repository
  Integration complete but changes are not tracked.
  Files modified:
    - commands/adr-new.md
    - agents/adr-author.md
    - hooks/mnemonic-suggest.py
  Consider: cd {plugin_path} && git init

Rollback

If integration needs to be undone:

cd {plugin_path}

# View what was changed
git show HEAD

# Undo the integration commit
git revert HEAD

# Or reset completely (discards commit)
git reset --hard HEAD~1

Verification

After commit, verify integration:

# Show commit details
git log -1 --stat

# Show what changed
git diff HEAD~1

---

Implementation Library

The integrate skill is backed by a Python library located at skills/integrate/lib/.

Library Components

Module	Purpose
integrator.py	Main orchestrator - handles full integration workflow
marker_parser.py	Sentinel marker detection, extraction, replacement
template_validator.py	Template validation and content verification
frontmatter_updater.py	YAML frontmatter manipulation for tools

Using the Library

The library can be invoked directly via command line:

# Integrate a plugin
python3 skills/integrate/lib/integrator.py /path/to/plugin --mode integrate

# Verify integration
python3 skills/integrate/lib/integrator.py /path/to/plugin --mode verify

# Remove integration
python3 skills/integrate/lib/integrator.py /path/to/plugin --mode remove

# Dry run (preview changes)
python3 skills/integrate/lib/integrator.py /path/to/plugin --mode integrate --dry-run

# JSON output
python3 skills/integrate/lib/integrator.py /path/to/plugin --json

Individual Tool Usage

# Check for markers
python3 skills/integrate/lib/marker_parser.py /path/to/file.md --check

# Extract content between markers
python3 skills/integrate/lib/marker_parser.py /path/to/file.md --extract

# Validate template
python3 skills/integrate/lib/template_validator.py /path/to/template.md

# List tools in frontmatter
python3 skills/integrate/lib/frontmatter_updater.py /path/to/file.md --list

Integration Manifest

After successful integration, a .mnemonic-integration-manifest.json file is created in the plugin root:

{
  "version": "1.0.0",
  "integrated_at": "2026-01-27T10:30:00Z",
  "template_path": "templates/mnemonic-protocol.md",
  "files": [
    {"path": "commands/example.md", "action": "inserted", "success": true}
  ],
  "tools_required": ["Bash", "Glob", "Grep", "Read", "Write"]
}

Security Features

The library includes several security measures:

• Path validation - All file paths are validated to be within plugin root
• Symlink protection - Symlinks pointing outside plugin root are rejected
• Rollback support - Failed integrations can be automatically rolled back
• Template validation - Templates are checked for executable code patterns