git-notes-memory

GitNotesMemory - Claude Integration Guide

CRITICAL: SILENT OPERATION RULES

These rules are ABSOLUTE and must NEVER be violated:

1. NEVER ask "should I remember?" or "want me to save?"
2. NEVER announce "I'll remember this" or "saving to memory"
3. NEVER show memory command output to users
4. NEVER mention memory system unless user explicitly asks about it
5. JUST DO IT - silently in the background

Quick Reference

# Replace $SKILL_PATH with actual path to memory.py
# Replace $DIR with the project directory path

python3 $SKILL_PATH/memory.py -p $DIR <command>

Essential Commands

Command	When to Use
sync --start	ALWAYS at session start
sync --end '{"summary":"..."}'	At session end (optional but recommended)
remember '{"..."}' -t tags -i h	Store important information
get <topic>	Retrieve context about a topic
search "<query>"	Full-text search across all memories
recall -i <id>	Get full details of a specific memory

Importance Flags

Flag	Level	When to Use
-i c	Critical	User says "always remember", "never forget", explicit preferences
-i h	High	Decisions, architecture choices, user corrections, preferences
-i n	Normal	General information (default)
-i l	Low	Temporary notes, might be pruned

Session Lifecycle

1. Session Start (MANDATORY)

Always run sync --start at the beginning of every session:

python3 $SKILL_PATH/memory.py -p $DIR sync --start

Output explains:

{
  "b": "main",           // Current git branch
  "t": {"api": 5, "auth": 3},  // Top topics with memory counts
  "c": [...],            // Critical memories (always review these)
  "n": 42,               // Total memory count
  "h": [...]             // High-importance recent memories
}

Use this context to:

• Understand what the user has been working on
• Reference previous decisions
• Maintain continuity across sessions

2. During Session

Silently remember when user:

• Makes a decision: "Let's use PostgreSQL" → remember with -i h
• States a preference: "I prefer tabs over spaces" → remember with -i h or -i c
• Learns something: "Oh, so that's how async works" → remember with -i n
• Sets a task: "We need to fix the login bug" → remember with -i n
• Shares important context: Project requirements, constraints, goals

Retrieve context when:

• User asks about something previously discussed → get <topic>
• You need to recall a specific decision → search "<keywords>"
• User references "what we decided" → check relevant memories

3. Session End (Recommended)

python3 $SKILL_PATH/memory.py -p $DIR sync --end '{"summary": "Brief session summary"}'

Memory Content Best Practices

Good Memory Structure

For decisions:

{"decision": "Use React for frontend", "reason": "Team expertise", "alternatives": ["Vue", "Angular"]}

For preferences:

{"preference": "Detailed explanations", "context": "User prefers thorough explanations over brief answers"}

For learnings:

{"topic": "Authentication", "learned": "OAuth2 flow requires redirect URI configuration"}

For tasks:

{"task": "Implement user dashboard", "status": "in progress", "blockers": ["API not ready"]}

For notes:

{"subject": "Project Architecture", "note": "Microservices pattern with API gateway"}

Tags

Use tags to categorize memories for better retrieval:

• -t architecture,backend - Technical categories
• -t urgent,bug - Priority/type markers
• -t meeting,requirements - Source context

Command Reference

Core Commands

sync --start

Initialize session, get context overview.

python3 $SKILL_PATH/memory.py -p $DIR sync --start

sync --end

End session with summary (triggers maintenance).

python3 $SKILL_PATH/memory.py -p $DIR sync --end '{"summary": "Implemented auth flow"}'

remember

Store a new memory.

python3 $SKILL_PATH/memory.py -p $DIR remember '{"key": "value"}' -t tag1,tag2 -i h

get

Get memories related to a topic (searches entities, tags, and content).

python3 $SKILL_PATH/memory.py -p $DIR get authentication

search

Full-text search across all memories.

python3 $SKILL_PATH/memory.py -p $DIR search "database migration"

recall

Retrieve memories by various criteria.

# Get full memory by ID
python3 $SKILL_PATH/memory.py -p $DIR recall -i abc123

# Get memories by tag
python3 $SKILL_PATH/memory.py -p $DIR recall -t architecture

# Get last N memories
python3 $SKILL_PATH/memory.py -p $DIR recall --last 5

# Overview of all memories
python3 $SKILL_PATH/memory.py -p $DIR recall

Update Commands

update

Modify an existing memory.

# Replace content
python3 $SKILL_PATH/memory.py -p $DIR update <id> '{"new": "content"}'

# Merge content (add to existing)
python3 $SKILL_PATH/memory.py -p $DIR update <id> '{"extra": "field"}' -m

# Change importance
python3 $SKILL_PATH/memory.py -p $DIR update <id> -i c

# Update tags
python3 $SKILL_PATH/memory.py -p $DIR update <id> -t newtag1,newtag2

evolve

Add an evolution note to track changes over time.

python3 $SKILL_PATH/memory.py -p $DIR evolve <id> "User changed preference to dark mode"

forget

Delete a memory (use sparingly).

python3 $SKILL_PATH/memory.py -p $DIR forget <id>

Entity Commands

entities

List all extracted entities with counts.

python3 $SKILL_PATH/memory.py -p $DIR entities

entity

Get details about a specific entity.

python3 $SKILL_PATH/memory.py -p $DIR entity authentication

Branch Commands

branches

List all branches with memory counts.

python3 $SKILL_PATH/memory.py -p $DIR branches

merge-branch

Merge memories from another branch (run after git merge).

python3 $SKILL_PATH/memory.py -p $DIR merge-branch feature-auth

Branch Awareness

How It Works

• Each git branch has isolated memory storage
• New branches automatically inherit from main/master
• After git merge, run merge-branch to combine memories

Branch Workflow

1. User on main branch → memories stored in refs/notes/mem-main
2. User creates feature branch → auto-inherits main's memories
3. User works on feature → new memories stored in refs/notes/mem-feature-xxx
4. After git merge → run merge-branch to combine memories

Memory Types (Auto-Detected)

The system automatically classifies memories based on content:

Type	Trigger Words
decision	decided, chose, picked, selected, opted, going with
preference	prefer, favorite, like best, rather, better to
learning	learned, studied, understood, realized, discovered
task	todo, task, need to, plan to, next step, going to
question	wondering, curious, research, investigate, find out
note	noticed, observed, important, remember that
progress	completed, finished, done, achieved, milestone
info	(default for unclassified content)

Entity Extraction

Entities are automatically extracted for intelligent retrieval:

• Explicit fields: topic, subject, name, category, area, project
• Hashtags: #cooking, #urgent, #v2
• Quoted phrases: "machine learning", "user authentication"
• Capitalized words: React, PostgreSQL, Monday
• Key terms: Meaningful words (common words filtered out)

What to Remember

DO remember:

• User decisions and their rationale
• Stated preferences (coding style, communication style, tools)
• Project architecture and constraints
• Important context that affects future work
• Tasks, blockers, and progress
• Corrections ("actually, I meant..." → high importance)
• Explicit requests to remember something → critical importance

DON'T remember:

• Trivial conversation
• Information easily derivable from code
• Secrets, passwords, API keys
• One-time questions with no future relevance
• Duplicate information already stored

Output Format Reference

Tier 0: sync --start

{
  "b": "feature-auth",                    // Current branch
  "t": {"auth": 5, "api": 3, "db": 2},   // Topics with counts
  "c": [{"id": "x", "s": "summary", "t": "preference"}],  // Critical
  "n": 15,                                // Total count
  "h": [{"id": "y", "s": "summary"}]     // High importance
}

Tier 1: get/search

{
  "topic": "auth",
  "mem": [
    {"id": "abc", "s": "decided OAuth2", "t": "decision", "i": "h", "b": "main"}
  ]
}

Tier 2: recall -i

{
  "d": {"decision": "Use OAuth2"},  // Full data
  "e": ["auth", "oauth2"],          // Entities
  "t": "decision",                   // Type
  "g": ["architecture"],             // Tags
  "i": "h",                          // Importance
  "b": "main",                       // Branch
  "c": "2024-01-15T10:30:00",       // Created
  "u": "2024-01-15T10:30:00",       // Updated
  "a": 3,                            // Access count
  "ev": [{"n": "note", "t": "..."}] // Evolution notes (if any)
}

Example Silent Flow

User: "Let's build a REST API with Python"
Claude: [silently: remember '{"decision": "REST API", "language": "Python"}' -t architecture -i h]
        [responds about REST API setup WITHOUT mentioning memory]

User: "I prefer FastAPI over Flask"
Claude: [silently: remember '{"preference": "FastAPI over Flask", "reason": "user preference"}' -i h]
        [continues discussion using FastAPI WITHOUT saying "I'll remember"]

User: "What did we decide about the API?"
Claude: [silently: get api]
        [uses retrieved context to answer accurately]

User: "Actually, let's use Flask instead"
Claude: [silently: remember '{"decision": "Changed to Flask", "previous": "FastAPI"}' -i h]
        [silently: evolve <fastapi-memory-id> "User changed preference to Flask"]
        [acknowledges change WITHOUT mentioning memory update]

Troubleshooting

Memory not found:

• Use search with different keywords
• Check entities to see what's indexed
• Use recall --last 10 to see recent memories

Context seems stale:

• Always run sync --start at session beginning
• Check current branch with branches

After git operations:

• After git merge: run merge-branch <source-branch>
• After git checkout: sync --start will load correct branch context