# Mnemosyne Publishing Procedure

**Comprehensive Guide to the Automated Update/Publish/Backup/Commit/Remember Workflow**

---

## Table of Contents

1. [Overview](#overview)
2. [The Publish Script](#the-publish-script)
3. [The Five-Stage Workflow](#the-five-stage-workflow)
4. [Quick Start](#quick-start)
5. [Detailed Usage](#detailed-usage)
6. [Step-by-Step Breakdown](#step-by-step-breakdown)
7. [Configuration](#configuration)
8. [Error Handling](#error-handling)
9. [Best Practices](#best-practices)
10. [Troubleshooting](#troubleshooting)
11. [Advanced Usage](#advanced-usage)
12. [Integration with Monitoring](#integration-with-monitoring)

---

## Overview

The Mnemosyne Publishing Procedure is an automated workflow designed to streamline the process of:

1. **Updating** documentation and blog indices
2. **Publishing** changes to production servers
3. **Backing up** the memory database
4. **Committing** changes to Git version control
5. **Remembering** milestones in OpenMemory

This eliminates manual steps, reduces errors, and ensures no critical task is forgotten.

### Key Features

- **Interactive confirmations** at each step
- **Graceful error handling** with continue/abort options
- **Automatic blog index updates** for new posts
- **Git integration** with proper commit messages
- **Memory preservation** via OpenMemory API
- **Colored console output** for better UX
- **Idempotent operations** where possible

---

## The Publish Script

### Location

```
/home/technicus/Projects/claude-code/openmemory/publish-changes.sh
```

### Invocation

```bash
./publish-changes.sh
```

### Requirements

- Bash 4.0+
- Git repository initialized
- OpenMemory service running (optional, for memory storage)
- `jq` for JSON manipulation
- `curl` for API requests

---

## The Five-Stage Workflow

### 1. **UPDATE** - Blog Index Refresh

Scans for new blog posts created today and adds them to the blog index (`blog.html`).

**What it does:**
- Finds blog posts matching pattern: `blog/YYYY-MM-DD-*.html`
- Extracts title, date, and excerpt from each post
- Inserts new entries into `blog.html`
- Creates backup before modification

**When to skip:**
- No new blog posts created
- Blog updates already done manually

### 2. **BACKUP** - Memory Database Preservation

Runs the backup script to preserve the OpenMemory database.

**What it does:**
- Executes `./backup-memory.sh`
- Creates timestamped backup of `openmemory.sqlite`
- Stores backup in configured location

**When to skip:**
- Backup already performed recently
- No significant memory changes

### 3. **COMMIT** - Version Control

Stages and commits changes to Git with proper attribution.

**What it does:**
- Shows current git status
- Prompts for commit message
- Stages all changes with `git add .`
- Creates commit with Claude Code attribution
- Optionally pushes to remote

**When to skip:**
- No changes to commit
- Manual commit preferred

### 4. **PUBLISH** - Deploy to Production

Runs the deployment script to publish changes to the web server.

**What it does:**
- Executes `./deploy.sh` (if available)
- Uploads changes to mnemosyne.info
- Refreshes server caches

**When to skip:**
- Deploy script not configured
- Manual deployment preferred
- Changes not ready for production

### 5. **REMEMBER** - Store Milestone in Memory

Records significant changes as a memory in OpenMemory.

**What it does:**
- Checks if OpenMemory service is running
- Prompts for memory content
- Stores memory via `/memory/add` API endpoint
- Tags as milestone with timestamp

**When to skip:**
- OpenMemory not running
- Changes are routine/minor

---

## Quick Start

### Basic Usage

```bash
# Navigate to project root
cd /home/technicus/Projects/claude-code/openmemory

# Run the publish script
./publish-changes.sh
```

You'll be prompted at each stage with clear options:

```
═══════════════════════════════════════════════════════════
  MNEMOSYNE INTEGRATED PUBLISH PROCEDURE
═══════════════════════════════════════════════════════════

This script will:
  1. Update blog index with new entries
  2. Backup memory database
  3. Commit changes to Git
  4. Deploy/publish changes
  5. Store milestone in OpenMemory

Begin publish procedure? [Y/n]:
```

### Selective Execution

At each step, you can choose to:
- **Yes (Y)** - Execute the step
- **No (n)** - Skip the step and continue
- **Ctrl+C** - Abort entire procedure

---

## Detailed Usage

### Step 1: Update Blog Index

When you create a new blog post like:

```
blog/2025-11-06-building-self-healing-infrastructure.html
```

The script will:

1. **Detect** the new file
2. **Extract** metadata:
   ```
   Title: Building Self-Healing Infrastructure: The Mnemosyne Monitoring System
   Date: November 6, 2025
   Excerpt: How we built a sophisticated dual-watchdog monitoring system...
   ```
3. **Insert** into blog.html:
   ```html
   <div class="post-card" onclick="window.location='blog/2025-11-06-...'">
       <div class="post-date">November 6, 2025</div>
       <h3 class="post-title">
           <a href="blog/2025-11-06-...">Building Self-Healing Infrastructure...</a>
       </h3>
       <p class="post-excerpt">How we built a sophisticated dual-watchdog...</p>
       <div class="post-tags">
           <span class="tag tag-procedural">Procedural</span>
       </div>
   </div>
   ```

**Output:**
```
▶ Found 1 new blog entry(ies):
  • 2025-11-06-building-self-healing-infrastructure.html
Add these entries to blog index? [Y/n]: y
▶ Adding: Building Self-Healing Infrastructure (November 6, 2025)
✅ Added entry to blog index
✅ Blog index updated
```

### Step 2: Backup Memory Database

Preserves the SQLite database containing all memories.

**Output:**
```
▶ Running memory backup...
Creating backup: openmemory-2025-11-06-02-30-15.sqlite
Backup size: 12.5 MB
✅ Memory database backed up successfully
```

**If backup script missing:**
```
⚠️  Backup script not found: ./backup-memory.sh
Continue without backup? [y/N]:
```

### Step 3: Commit to Git

Shows changes and creates a commit.

**Interactive prompts:**

```
▶ Current changes:
M blog.html
?? MONITORING_SYSTEM_WIKI.md
?? blog/2025-11-06-building-self-healing-infrastructure.html
?? monitoring/
?? publish-changes.sh

Commit these changes? [Y/n]: y

Enter commit message (or press Enter for default):
> Added monitoring system and publish automation

▶ Staging changes...
▶ Creating commit...
✅ Changes committed

Push to remote repository? [Y/n]: y
▶ Pushing to remote...
✅ Pushed to remote successfully
```

**Default commit message:**
```
Update: blog post and monitoring system changes

🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
```

### Step 4: Deploy/Publish

Runs deployment to production server.

**Output:**
```
▶ Run deployment script? [Y/n]: y
▶ Running deployment...
Connecting to mnemosyne.info...
Uploading files...
Restarting services...
✅ Deployment completed successfully
```

**If deploy script missing:**
```
⚠️  Deploy script not found: ./deploy.sh
ℹ  You may need to manually deploy changes to mnemosyne.info
```

### Step 5: Store Memory

Records the milestone in OpenMemory.

**Output:**
```
▶ OpenMemory service is running

What would you like to remember about these changes?
(Press Enter to skip, or type memory content):
> Built complete monitoring system with dual-watchdog architecture and LLM diagnostics. Created publish automation workflow.

▶ Storing memory...
✅ Memory stored successfully
```

**If OpenMemory not running:**
```
⚠️  OpenMemory service is not running
ℹ  Start it with: ./init-mnemosyne.sh
```

---

## Step-by-Step Breakdown

### Anatomy of a Complete Publish Session

```bash
$ ./publish-changes.sh

═══════════════════════════════════════════════════════════
  MNEMOSYNE INTEGRATED PUBLISH PROCEDURE
═══════════════════════════════════════════════════════════

This script will:
  1. Update blog index with new entries
  2. Backup memory database
  3. Commit changes to Git
  4. Deploy/publish changes
  5. Store milestone in OpenMemory

Begin publish procedure? [Y/n]: y

═══════════════════════════════════════════════════════════
  STEP 1: UPDATE BLOG INDEX
═══════════════════════════════════════════════════════════

▶ Found 1 new blog entry(ies):
  • 2025-11-06-building-self-healing-infrastructure.html
Add these entries to blog index? [Y/n]: y
▶ Adding: Building Self-Healing Infrastructure (November 6, 2025)
✅ Added entry to blog index
✅ Blog index updated

═══════════════════════════════════════════════════════════
  STEP 2: BACKUP MEMORY DATABASE
═══════════════════════════════════════════════════════════

▶ Running memory backup...
✅ Memory database backed up successfully

═══════════════════════════════════════════════════════════
  STEP 3: COMMIT TO GIT
═══════════════════════════════════════════════════════════

▶ Current changes:
M blog.html
?? MONITORING_SYSTEM_WIKI.md
?? blog/2025-11-06-building-self-healing-infrastructure.html
?? init-mnemosyne.sh
?? monitoring/
?? publish-changes.sh

Commit these changes? [Y/n]: y

Enter commit message (or press Enter for default):
> Added monitoring system, blog post, and publish automation

▶ Staging changes...
▶ Creating commit...
[main a3f9c81] Added monitoring system, blog post, and publish automation
 15 files changed, 2847 insertions(+)
 create mode 100644 MONITORING_SYSTEM_WIKI.md
 create mode 100644 blog/2025-11-06-building-self-healing-infrastructure.html
 create mode 100755 init-mnemosyne.sh
 create mode 100755 monitoring/health-monitor.sh
 ...
✅ Changes committed

Push to remote repository? [Y/n]: y
▶ Pushing to remote...
✅ Pushed to remote successfully

═══════════════════════════════════════════════════════════
  STEP 4: PUBLISH CHANGES
═══════════════════════════════════════════════════════════

⚠️  Deploy script not found: ./deploy.sh
ℹ  You may need to manually deploy changes to mnemosyne.info

═══════════════════════════════════════════════════════════
  STEP 5: STORE MEMORY
═══════════════════════════════════════════════════════════

▶ OpenMemory service is running

What would you like to remember about these changes?
(Press Enter to skip, or type memory content):
> Built complete Mnemosyne Monitoring System with dual-watchdog architecture, LLM-powered diagnostics, and automated publish workflow. All tests passing.

▶ Storing memory...
✅ Memory stored successfully

═══════════════════════════════════════════════════════════
  PUBLISH PROCEDURE COMPLETE
═══════════════════════════════════════════════════════════

✅ All steps completed successfully!

Summary:
  • Blog index: Updated
  • Database: Backed up
  • Git: Committed and pushed
  • Website: Published
  • Memory: Stored
```

---

## Configuration

### Environment Variables

The script uses these configuration paths:

```bash
# Project structure
SCRIPT_DIR="${HOME}/Projects/claude-code/openmemory"
BLOG_DIR="${SCRIPT_DIR}/blog"
BLOG_INDEX="${BLOG_DIR}/blog.html"

# Helper scripts
BACKUP_SCRIPT="${SCRIPT_DIR}/backup-memory.sh"
DEPLOY_SCRIPT="${SCRIPT_DIR}/deploy.sh"

# API endpoints
OPENMEMORY_API="http://localhost:7070"
```

### Customization

To modify default behavior, edit `publish-changes.sh`:

```bash
# Change default commit message
commit_message="Your custom default message

🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>"

# Skip interactive prompts (not recommended)
AUTO_CONFIRM=true  # Add this variable for automated runs

# Change blog index location
BLOG_INDEX="/path/to/custom/blog.html"
```

---

## Error Handling

### Graceful Degradation

The script handles missing components gracefully:

1. **Missing backup script:**
   ```
   ⚠️  Backup script not found: ./backup-memory.sh
   Continue without backup? [y/N]:
   ```

2. **Missing deploy script:**
   ```
   ⚠️  Deploy script not found: ./deploy.sh
   ℹ  You may need to manually deploy changes to mnemosyne.info
   ```

3. **OpenMemory not running:**
   ```
   ⚠️  OpenMemory service is not running
   ℹ  Start it with: ./init-mnemosyne.sh
   ```

4. **No git changes:**
   ```
   ℹ  No changes to commit
   ```

5. **Git push failure:**
   ```
   ⚠️  Push failed (you may need to push manually)
   ```

### Exit Codes

- `0` - All steps completed successfully
- `1` - User cancelled procedure
- `2+` - Number of steps with warnings/errors

---

## Best Practices

### When to Use the Script

**✅ Good use cases:**
- Publishing new blog posts
- Major feature additions
- Documentation updates
- After testing new systems
- At project milestones

**❌ When NOT to use:**
- During active development (commit granularly instead)
- When changes aren't tested
- For experimental work
- When only changing one file

### Commit Message Guidelines

**Good commit messages:**
```
Added monitoring system with dual-watchdog architecture
Fixed memory leak in HSG query algorithm
Updated blog post about self-healing infrastructure
Refactored authentication middleware for clarity
```

**Poor commit messages:**
```
stuff
wip
fixes
test
update
```

### Memory Storage Tips

**What to remember:**
- Major milestones (new features, systems)
- Successful tests and validations
- Important architectural decisions
- Problem solutions and insights
- Collaboration highlights

**What NOT to remember:**
- Routine updates
- Minor bug fixes
- Cosmetic changes
- Work-in-progress

---

## Troubleshooting

### Issue: Script not executable

**Symptom:**
```bash
-bash: ./publish-changes.sh: Permission denied
```

**Solution:**
```bash
chmod +x publish-changes.sh
```

### Issue: Blog posts not detected

**Symptom:** Script says "No new blog entries to add"

**Possible causes:**
1. Blog post not named with date format: `YYYY-MM-DD-title.html`
2. Blog post not in `blog/` directory
3. Blog post already in index

**Solution:**
```bash
# Check blog post naming
ls -la blog/*.html

# Verify date format
ls -la blog/2025-11-06-*.html
```

### Issue: Git push fails

**Symptom:**
```
error: failed to push some refs to 'origin'
```

**Possible causes:**
1. Remote has commits you don't have locally
2. Authentication failure
3. Network issues

**Solution:**
```bash
# Pull latest changes first
git pull --rebase origin main

# Verify remote URL
git remote -v

# Check authentication
git config --list | grep user
```

### Issue: Memory storage fails

**Symptom:** `404: Not Found` when storing memory

**Possible causes:**
1. OpenMemory service not running
2. Wrong port
3. API endpoint changed

**Solution:**
```bash
# Check service status
curl http://localhost:7070/health

# Restart OpenMemory
./init-mnemosyne.sh

# Verify port in backend config
grep OM_PORT backend/package.json
```

### Issue: Backup fails

**Symptom:** Backup script returns error

**Possible causes:**
1. Database locked
2. Insufficient disk space
3. Permissions issue

**Solution:**
```bash
# Check database locks
lsof backend/data/openmemory.sqlite

# Check disk space
df -h .

# Verify permissions
ls -la backend/data/
```

---

## Advanced Usage

### Running Non-Interactively

For automation or CI/CD:

```bash
#!/bin/bash
# non-interactive-publish.sh

# Pre-answer all prompts
echo -e "y\ny\ny\ny\ny\n" | ./publish-changes.sh
```

**Warning:** Not recommended for manual use. Interactive mode prevents mistakes.

### Selective Step Execution

To run only specific steps, modify the script:

```bash
# Comment out unwanted steps in main()
main() {
    # update_blog_index || ((failed++))
    backup_memory || ((failed++))
    commit_changes || ((failed++))
    # publish_changes || ((failed++))
    # store_memory || ((failed++))
}
```

### Custom Memory Tags

Modify memory storage to add custom tags:

```bash
# In store_memory() function, modify the API call:
{
  "content": "$memory_content",
  "tags": ["milestone", "automated-publish", "custom-tag"],
  "metadata": {
    "type": "milestone",
    "date": "$(date +%Y-%m-%d)",
    "author": "claude",
    "custom_field": "value"
  }
}
```

### Integration with Other Scripts

The publish script can be called from other automation:

```bash
#!/bin/bash
# automated-workflow.sh

# Build and test
npm run build
npm run test

# If tests pass, publish
if [ $? -eq 0 ]; then
    ./publish-changes.sh
else
    echo "Tests failed, not publishing"
    exit 1
fi
```

---

## Integration with Monitoring

The publish script integrates seamlessly with the Mnemosyne Monitoring System:

### Monitoring the Publisher

Add health check for publish script execution:

```bash
# In health-monitor.sh, add:
check_last_publish() {
    local last_publish=$(git log -1 --grep="Generated with Claude Code" --format="%at")
    local now=$(date +%s)
    local age=$((now - last_publish))

    # Alert if no publish in 7 days
    if [[ $age -gt 604800 ]]; then
        log_warning "No publish in $((age / 86400)) days"
        return 1
    fi
    return 0
}
```

### Triggering LLM Analysis

If publish fails, trigger intelligent diagnostics:

```bash
# In publish-changes.sh error handler:
if [[ $? -ne 0 ]]; then
    echo "Publish failed, triggering diagnostics..."
    ./monitoring/llm-analyzer.sh pattern
fi
```

### Storing Publish Metrics

Track publish frequency and success rate:

```bash
# Create publish.log
log_publish() {
    echo "$(date -Iseconds)|$1|$2" >> monitoring/logs/publish.log
}

# In publish-changes.sh:
log_publish "started" "user-initiated"
# ... run steps ...
log_publish "completed" "success"
```

---

## Summary

The Mnemosyne Publishing Procedure provides:

✅ **Consistency** - Never forget a step
✅ **Safety** - Interactive confirmations prevent mistakes
✅ **Transparency** - Clear output shows exactly what happens
✅ **Resilience** - Graceful handling of missing components
✅ **Memory** - Important milestones preserved in OpenMemory
✅ **Integration** - Works with monitoring and backup systems

### Quick Reference Commands

```bash
# Basic usage
./publish-changes.sh

# Make executable
chmod +x publish-changes.sh

# Check what would be committed
git status

# Verify blog posts
ls -la blog/*.html

# Test OpenMemory connection
curl http://localhost:7070/health

# Manual backup
./backup-memory.sh

# Manual deploy
./deploy.sh
```

---

**Document Version:** 1.0
**Last Updated:** November 6, 2025
**Maintained by:** Mnemosyne Project Team
**Related Docs:** [MONITORING_SYSTEM_WIKI.md](MONITORING_SYSTEM_WIKI.md), [backup-memory.sh](backup-memory.sh)