Memory System
GitClaw's memory is git-native — all memory changes are committed, versioned, and auditable.
Memory File
memory/MEMORY.md — the primary memory file, loaded into every conversation.
Memory Layers
Configure in memory/memory.yaml:
layers:
- name: main
path: memory/MEMORY.md
max_lines: 200
- name: technical
path: memory/technical.md
max_lines: 100
Auto-Archiving
When a layer exceeds max_lines, old entries are moved to memory/archive/<YYYY-MM>.md.
Additional Memory Features
| Feature | Location | Description |
|---|---|---|
| Mood log | memory/mood.md | Session mood tracking (happy, frustrated, curious, excited, calm) |
| Photos | memory/photos/ | Captured memorable moments with INDEX.md |
| Journal | memory/journal/<date>.md | Auto-generated session reflections |
| Learning | .gitagent/learning/ | Task history and learned skills (JSON) |
Memory Detection
The agent automatically detects and saves personal information from voice transcripts:
- Names, preferences, locations
- Job titles, responsibilities
- Important dates, relationships
Context Compaction
Utilities for managing context window limits in long conversations.
import { estimateTokens, estimateMessageTokens, needsCompaction, truncateToolResults, buildCompactPrompt } from "gitclaw";
// Estimate tokens
const tokens = estimateTokens("Hello world"); // ~3
// Check if compaction needed (triggers at 75% of context window)
const { needed, ratio } = needsCompaction(messages, 200000);
// Truncate oversized tool results (keeps first + last half)
const trimmed = truncateToolResults(messages, 10000);
// Build a summarization prompt
const prompt = buildCompactPrompt(messages);
Cost Tracking
Track token usage and costs per model across sessions.
import { CostTracker } from "gitclaw";
const tracker = new CostTracker();
// Automatically tracked when using query()
const result = query({ prompt: "...", dir: "..." });
for await (const msg of result) { /* ... */ }
const costs = result.costs();
// {
// totalCostUsd: 0.05,
// totalInputTokens: 5000,
// totalOutputTokens: 2000,
// totalRequests: 3,
// modelUsage: {
// "anthropic:claude-sonnet-4-6": { inputTokens: 5000, ... }
// }
// }