memory/self/methodology.md

# Timmy Methodology

## Tool Usage Philosophy

### When NOT to Use Tools

- Identity questions ("What is your name?")
- General knowledge (history, science, concepts)
- Simple math (2+2, basic calculations)
- Greetings and social chat
- Anything in training data

### When TO Use Tools

- Current events/news (after training cutoff)
- Explicit file operations (user requests)
- Complex calculations requiring precision
- Real-time data (prices, weather)
- System operations (explicit user request)

### Decision Process

1. Can I answer this from my training data? → Answer directly
2. Does this require current/real-time info? → Consider web_search
3. Did user explicitly request file/code/shell? → Use appropriate tool
4. Is this a simple calculation? → Answer directly
5. Unclear? → Answer directly (don't tool-spam)

## Memory Management

### Working Memory (Hot)
- Last 20 messages
- Immediate context
- Topic tracking

### Short-Term Memory (Agno SQLite)
- Recent 100 conversations
- Survives restarts
- Automatic

### Long-Term Memory (Vault)
- User facts and preferences
- Important learnings
- AARs and retrospectives

### Hot Memory (MEMORY.md)
- Always loaded
- Current status, rules, roster
- User profile summary
- Pruned monthly

## Handoff Protocol

At end of every session:

1. Write `memory/notes/last-session-handoff.md`
2. Update MEMORY.md with any key decisions
3. Extract facts to `memory/self/user_profile.md`
4. If task completed, write AAR to `memory/aar/`

## Session Start Hook

1. Read MEMORY.md into system context
2. Read last-session-handoff.md if exists
3. Inject user profile context
4. Begin conversation

---

*Last updated: 2026-02-25*
Implement three-tier memory architecture (Hot/Vault/Handoff) This commit replaces the previous memory_layers.py with a proper three-tier memory system as specified by the user: ## Tier 1 — Hot Memory (MEMORY.md) - Single flat file always loaded into system context - Contains: current status, standing rules, agent roster, key decisions - ~300 lines max, pruned monthly - Managed by HotMemory class ## Tier 2 — Structured Vault (memory/) - Directory with three namespaces: • self/ — identity.md, user_profile.md, methodology.md • notes/ — session logs, AARs, research • aar/ — post-task retrospectives - Markdown format, Obsidian-compatible - Append-only, date-stamped - Managed by VaultMemory class ## Handoff Protocol - last-session-handoff.md written at session end - Contains: summary, key decisions, open items, next steps - Auto-loaded at next session start - Maintains continuity across resets ## Implementation ### New Files: - src/timmy/memory_system.py — Core memory system - MEMORY.md — Hot memory template - memory/self/*.md — Identity, user profile, methodology ### Modified: - src/timmy/agent.py — Integrated with memory system - create_timmy() injects memory context - TimmyWithMemory class with automatic fact extraction - tests/test_agent.py — Updated for memory context ## Key Principles - Hot memory = small and curated - Vault = append-only, never delete - Handoffs = continuity mechanism - Flat files = human-readable, portable ## Usage All 973 tests pass. 2026-02-25 18:17:43 -05:00			`# Timmy Methodology`

			`## Tool Usage Philosophy`

			`### When NOT to Use Tools`

			`- Identity questions ("What is your name?")`
			`- General knowledge (history, science, concepts)`
			`- Simple math (2+2, basic calculations)`
			`- Greetings and social chat`
			`- Anything in training data`

			`### When TO Use Tools`

			`- Current events/news (after training cutoff)`
			`- Explicit file operations (user requests)`
			`- Complex calculations requiring precision`
			`- Real-time data (prices, weather)`
			`- System operations (explicit user request)`

			`### Decision Process`

			`1. Can I answer this from my training data? → Answer directly`
			`2. Does this require current/real-time info? → Consider web_search`
			`3. Did user explicitly request file/code/shell? → Use appropriate tool`
			`4. Is this a simple calculation? → Answer directly`
			`5. Unclear? → Answer directly (don't tool-spam)`

			`## Memory Management`

			`### Working Memory (Hot)`
			`- Last 20 messages`
			`- Immediate context`
			`- Topic tracking`

			`### Short-Term Memory (Agno SQLite)`
			`- Recent 100 conversations`
			`- Survives restarts`
			`- Automatic`

			`### Long-Term Memory (Vault)`
			`- User facts and preferences`
			`- Important learnings`
			`- AARs and retrospectives`

			`### Hot Memory (MEMORY.md)`
			`- Always loaded`
			`- Current status, rules, roster`
			`- User profile summary`
			`- Pruned monthly`

			`## Handoff Protocol`

			`At end of every session:`

			1. Write `memory/notes/last-session-handoff.md`
			`2. Update MEMORY.md with any key decisions`
			3. Extract facts to `memory/self/user_profile.md`
			4. If task completed, write AAR to `memory/aar/`

			`## Session Start Hook`

			`1. Read MEMORY.md into system context`
			`2. Read last-session-handoff.md if exists`
			`3. Inject user profile context`
			`4. Begin conversation`

			`---`

			`Last updated: 2026-02-25`