hermes-skills/memory-sync/SKILL.md

name, description, version, category, tags

name	description	version	category	tags
memory-sync	Set up and maintain a markdown-based personal memory system with qmd semantic search and Git/Gitea sync. Based on Karpathy's LLM Wiki pattern. Covers wiki structure, qmd search setup, git sync, and maintenance protocol.	2.0.0	research	wiki memory qmd gitea git-sync knowledge-base markdown semantic-search

Memory Sync

Set up and maintain a markdown-based personal memory system using qmd for semantic search and Git/Gitea for version control.

This umbrella skill covers:

• Wiki setup and maintenance — directory structure, git sync, session log protocol
• qmd semantic search — BM25, vector embeddings, LLM reranking for the wiki
• MCP server integration (optional) — HTTP transport for LLM tool access

Quick Setup

1. Install qmd (Query Markup Documents)

# Check for Node.js
node --version 2>/dev/null || echo "Not installed"

# If not installed, download Node.js for x86_64:
curl -fsSL https://nodejs.org/dist/v20.11.0/node-v20.11.0-linux-x64.tar.xz -o /tmp/node.tar.xz
tar -xJf /tmp/node.tar.xz -C /tmp/
export PATH="/tmp/node-v20.11.0-linux-x64/bin:$PATH"

# Install qmd
npm install -g @tobilu/qmd

2. Create Memory Directory

mkdir -p ~/.hermes/memory
cd ~/.hermes/memory

# Add as qmd collection
qmd collection add ~/.hermes/memory --name memory

# Add context for better search results
qmd context add qmd://memory "Personal knowledge base using Karpathy LLM Wiki pattern"

# Generate embeddings (downloads model on first run, ~250MB)
qmd embed

3. Set Up Git Sync

cd ~/.hermes/memory
git init
git config user.name "Your Name"
git config user.email "your@email.com"

# Add remote (Gitea HTTPS with token auth)
git remote add origin "https://USER:TOKEN@git.familie-schoen.com/USER/memory.git"

# Push to main branch
git branch -m master main 2>/dev/null
git push -u origin main

4. Create Initial Structure

~hermes/memory/
├── index.md              # Content catalog
├── log.md                # Chronological log (append-only)
├── Entities/
│   └── *.md              # Entity pages (person, system, tool)
├── Concepts/
│   └── *.md              # Concept pages (architecture, workflow)
├── Projects/             # Empty — future project pages
├── Templates/            # Empty — future templates
└── memory-entry-NNN.md   # Session log entries (numbered)

The index.md links to subdirectory pages using relative paths: [[Entities/Infrastructure.md]].

Maintenance Protocol (CRITICAL)

The memory must be kept current at ALL times. This is not optional.

Start of Session

1. Read log.md and check git status to see what was last synced
2. Read index.md to understand current state
3. If memory is stale, correct it before proceeding with any task
4. Use hindsight_recall or direct file reads to verify facts before answering

End of Session

1. Append to log.md with today's changes
2. Create memory-entry-NNN.md (next available number) summarizing the session
3. Update index.md if new entities/concepts were created
4. Commit and push:

   cd ~/.hermes/memory && git add . && git commit -m "Update: brief description" && git push
   

5. Verify push succeeded before ending the session

Never

• Do NOT use hindsight_retain for memory files — the daemon is not available and will silently fail
• Do NOT commit without pushing — unsynced memory is stale memory
• Do NOT let memory files go stale between sessions

Sync Workflow

Manual Sync

cd ~/.hermes/memory
git add .
git commit -m "Description" && git push 2>/dev/null || echo "No changes"
qmd embed 2>/dev/null  # Re-index new files

Automatic Sync (cron — script-only, no agent)

For purely git-based sync operations, use --no-agent to skip the LLM entirely (saves time/cost):

hermes cron create \
  --name "memory-sync-daily" \
  --schedule "0 22 * * *" \
  --script 'cd ~/.hermes/memory && git add . && git commit -m "Auto-sync: $(date +%%Y-%%m-%%d)" && git push origin main' \
  --no-agent

Memory Entry Format

Use numbered entries for session logs:

# Memory Entry 001 - System Initialization

## Date
2026-04-28

## Summary
Brief description of what was done.

## Details
- [x] Task 1
- [x] Task 2
- [ ] Task 3 (pending)

## Status
- Completed items
- Pending items

## Notes
Additional context or questions.

Pitfalls

• qmd embed may not index new files — if files were added after collection creation, recreate the collection: qmd collection rm memory && qmd collection add ~/.hermes/memory --name memory && qmd embed
• First qmd embed downloads a model — ~250MB, may take minutes
• Token scope — Gitea tokens need write:repository scope for push access
• Branch naming — Gitea repos default to main, local git may create master — rename with git branch -m master main
• HTTPS vs SSH — When SSH is blocked, use HTTPS with token in URL: https://USER:TOKEN@git.server.com/USER/repo.git
• hindsight_retain silently fails — the daemon is not available; use direct file edits + git instead
• Memory goes stale between sessions — always start by reading log.md and checking git status

When to Use

• Setting up a new memory/knowledge system
• Adding semantic search to a markdown wiki
• Syncing memory files to Gitea/GitHub
• Creating structured memory entries after sessions
• Maintaining up-to-date knowledge base across sessions

Search Commands

# Fast keyword search (BM25)
qmd search "authentication"

# Semantic search (embedding-based)
qmd vsearch "how to deploy"

# Hybrid + LLM reranking (best quality)
qmd query "quarterly planning process"

# Get a specific document
qmd get "meetings/2024-01-15.md"

# Search within a specific collection
qmd search "API" -c wiki

# JSON output for agents
qmd search "authentication" --json -n 10

MCP Server (Optional)

# Start MCP server (HTTP transport)
qmd mcp --http

# Start as daemon
qmd mcp --http --daemon

# Stop
qmd mcp stop

# Check status
qmd status

Configure MCP clients to connect to http://localhost:8181/mcp.

Pitfalls

• qmd embed may not index new files — if files were added after collection creation, recreate: qmd collection rm wiki && qmd collection add $WIKI --name wiki && qmd embed
• First qmd embed downloads model — ~250MB, may take minutes
• Node.js version — qmd requires Node.js 20.17.0+ for some deps
• Memory usage — ~1GB RAM when model is loaded