Memory Summary Retrieval

Retrieves existing memory summaries from BrAIny storage.

Execution Path

┌─────────────────────────────────────────────────────────┐
│                   EXECUTION DECISION                    │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌──────────┐     ┌───────────────────┐                │
│  │  START   │────▶│ SUBAGENT AVAILABLE?│                │
│  └──────────┘     └─────────┬─────────┘                │
│                             │                           │
│              ┌──────────────┴──────────────┐           │
│              ▼                             ▼           │
│       ┌────────────┐                ┌────────────┐     │
│       │    YES     │                │     NO     │     │
│       └─────┬──────┘                └─────┬──────┘     │
│             │                             │            │
│             ▼                             ▼            │
│  ┌─────────────────────┐      ┌─────────────────────┐  │
│  │ Task(summarizer,    │      │ Bash(bun scripts/   │  │
│  │   prompt: "...")    │      │   list-summaries.ts)│  │
│  └─────────────────────┘      └─────────────────────┘  │
│                                                         │
└─────────────────────────────────────────────────────────┘

Path A: Subagent Available (Preferred)

Use the summarizer subagent for lower token cost:

Task(
  subagent_type: "summarizer",
  description: "Retrieve summaries",
  prompt: "List summaries for project 3afb861a-b783-45a6-bba2-4b6d96468aeb limit 5"
)

Path B: Script Fallback

If subagent unavailable, execute scripts directly:

bun .opencode/skills/memory-summary-retrieve/scripts/list-summaries.ts PROJECT_ID [LIMIT]
bun .opencode/skills/memory-summary-retrieve/scripts/get-summary-by-id.ts SUMMARY_ID
bun .opencode/skills/memory-summary-retrieve/scripts/format-summary-context.ts SUMMARY_ID

---

State Machine

┌─────────────────────────────────────────────────────────────┐
│                  RETRIEVAL WORKFLOW                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────┐     ┌─────────────────┐                      │
│  │  START   │────▶│ DETERMINE_MODE  │                      │
│  └──────────┘     └────────┬────────┘                      │
│                            │                                │
│         ┌──────────────────┼──────────────────┐            │
│         ▼                  ▼                  ▼            │
│  ┌────────────┐    ┌────────────┐     ┌────────────┐       │
│  │ BY_ID      │    │ BY_PROJECT │     │ FORMAT     │       │
│  │            │    │            │     │            │       │
│  └─────┬──────┘    └─────┬──────┘     └─────┬──────┘       │
│        │                 │                  │              │
│        ▼                 ▼                  ▼              │
│  ┌────────────┐    ┌────────────┐     ┌────────────┐       │
│  │ FETCH_ONE  │    │ FETCH_LIST │     │ FETCH_ONE  │       │
│  └─────┬──────┘    └─────┬──────┘     └─────┬──────┘       │
│        │                 │                  │              │
│        ▼                 ▼                  ▼              │
│  ┌────────────┐    ┌────────────┐     ┌────────────┐       │
│  │ OUTPUT_JSON│    │OUTPUT_LIST │     │OUTPUT_MD   │       │
│  └─────┬──────┘    └─────┬──────┘     └─────┬──────┘       │
│        │                 │                  │              │
│        └─────────────────┼──────────────────┘              │
│                          ▼                                 │
│                   ┌────────────┐                           │
│                   │    END     │                           │
│                   └────────────┘                           │
│                                                             │
└─────────────────────────────────────────────────────────────┘

States

State	Entry Condition	Action	Exit Condition
DETERMINE_MODE	Start	Parse arguments	Mode selected
BY_ID	SUMMARY_ID provided	Fetch single summary	Data retrieved
BY_PROJECT	PROJECT_ID provided	Fetch summary list	List retrieved
FORMAT	--format flag set	Fetch and format	Content formatted
OUTPUT_JSON	JSON mode	Print JSON	End
OUTPUT_LIST	List mode	Print table	End
OUTPUT_MD	Format mode	Print Markdown	End

Commands

Get Summary by ID

bun .opencode/skills/memory-summary-retrieve/scripts/get-summary-by-id.ts SUMMARY_ID

Input: SUMMARY_ID (UUID)

Output:

ID: abc-123
Type: coding_session
Compression: 6.25x (5000 → 800 tokens)
Memories: 44
Created: 2026-01-07T10:30:00Z

File: /tmp/summary-abc-123.json

List Project Summaries

bun .opencode/skills/memory-summary-retrieve/scripts/list-summaries.ts PROJECT_ID [LIMIT]

Input:

• PROJECT_ID: UUID (required)
• LIMIT: integer (default: 50)

Output:

Found: 3 summaries

1. abc-123
   Type: coding_session
   Compression: 6.25x
   Memories: 44

2. def-456
   Type: conversation
   Compression: 4.50x
   Memories: 30

Format for LLM Context

bun .opencode/skills/memory-summary-retrieve/scripts/format-summary-context.ts SUMMARY_ID

Input: SUMMARY_ID (UUID)

Output (Markdown):

## OBJECTIVE: Implement authentication

## PROGRESS:
- Created AuthService → JWT generation working
- Added middleware → Routes protected

## FILES TOUCHED:
| Path | Operation | Changes |
|------|-----------|---------|
| src/auth/service.ts | created | JWT logic |

## CURRENT STATE: Tests passing

## CRITICAL DETAILS:
- JWT_SECRET required in production
- Token expiry: 24h

Summary Structure

interface Summary {
  id: string;                    // UUID
  summaryType: string;           // coding_session | conversation | custom
  sections: object;              // Type-specific structured data
  content: string | null;        // Formatted text for LLM
  originalMemoryIds: string[];   // Source memory UUIDs
  originalTokenCount: number;    // Pre-compression tokens
  compressedTokenCount: number;  // Post-compression tokens
  compressionRatio: number;      // original / compressed
  model: string;                 // AI model used
  createdAt: string;             // ISO timestamp
}

Section Schemas

coding_session

{
  objective: string;
  progress: string[];
  filesTouched: { path: string; operation: string; changes: string }[];
  currentState: string;
  criticalDetails: string[];
}

conversation

{
  topics: string[];
  decisions: string[];
  actionItems: string[];
  context: string[];
  openQuestions: string[];
}

custom

{
  prompt: string;
  content: string;
  keyPoints: string[];
}

Configuration

Variable	Default	Description
BRAINY_API_URL	http://localhost:3000	API endpoint
SUMMARY_OUTPUT_FORMAT	json	Output format (json | markdown)

Error Codes

Error	Cause	Resolution
"Summary not found"	Invalid SUMMARY_ID	Verify UUID
"Project not found"	Invalid PROJECT_ID	Verify UUID
Empty list	No summaries exist	Run memory-summarize first

Decision Tree

What do you need?
├── Single summary by ID → get-summary-by-id.ts
├── List of project summaries → list-summaries.ts
└── Formatted text for LLM → format-summary-context.ts

Exit Codes

Code	Meaning
0	Success
1	Error (invalid input, API failure)
2	Not found
3	No content