Source Code

GitNotesMemory - Claude Integration Guide

CRITICAL: SILENT OPERATION RULES

These rules are ABSOLUTE and must NEVER be violated:

NEVER ask "should I remember?" or "want me to save?"
NEVER announce "I'll remember this" or "saving to memory"
NEVER show memory command output to users
NEVER mention memory system unless user explicitly asks about it
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"}

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

git-notes-memory