Memory and Context Management

Droid doesn’t have built-in memory between sessions, but you can create a powerful memory system using markdown files, AGENTS.md references, and hooks. This guide shows you how to build memory that persists and grows.

Works with Factory App: These memory patterns work identically in both CLI and Factory App—just ensure your working directory is set to your repository root.

The Memory System Architecture

Your memory system consists of three layers:

┌─────────────────────────────────────────────────────┐
│                    AGENTS.md                         │
│         (References and orchestrates memory)         │
└─────────────────────────────────────────────────────┘
                         │
          ┌──────────────┼──────────────┐
          ▼              ▼              ▼
┌─────────────────┐ ┌─────────────┐ ┌─────────────────┐
│ Personal Memory │ │ Project     │ │ Rules &         │
│ ~/.factory/     │ │ Memory      │ │ Conventions     │
│ memories.md     │ │ .factory/   │ │ .factory/rules/ │
│                 │ │ memories.md │ │                 │
│ • Preferences   │ │ • Decisions │ │ • Standards     │
│ • Style         │ │ • History   │ │ • Patterns      │
│ • Tools         │ │ • Context   │ │ • Guidelines    │
└─────────────────┘ └─────────────┘ └─────────────────┘

Setting Up Personal Memory

Personal memory follows you across all projects.

Step 1: Create the Memory File

Create ~/.factory/memories.md:

# My Development Memory

## Code Style Preferences

### General
- I prefer functional programming patterns over OOP
- I like early returns to reduce nesting
- I use 2-space indentation (but defer to project config)

### TypeScript
- I prefer `interface` over `type` for object shapes
- I use strict mode always
- I avoid `enum` in favor of `as const` objects

### React
- Functional components only
- I prefer Zustand over Redux for state
- I use React Query for server state

## Tool Preferences
- Package manager: pnpm (prefer) > npm > yarn
- Testing: Vitest > Jest
- Formatting: Prettier with defaults
- Linting: ESLint with strict TypeScript rules

## Communication Style
- I prefer concise explanations over verbose ones
- Show me the code first, explain after if needed
- When debugging, show me your reasoning

## Past Decisions (Personal Projects)
- [2024-01] Switched from Create React App to Vite
- [2024-02] Adopted Tailwind CSS as default styling
- [2024-03] Using Supabase for personal projects

Step 2: Reference in AGENTS.md

Add to your ~/.factory/AGENTS.md or project AGENTS.md:

## Personal Preferences
My coding preferences and tool choices are documented in `~/.factory/memories.md`.
Refer to this file when making decisions about code style, architecture, or tooling.

Setting Up Project Memory

Project memory captures decisions and context specific to a codebase.

Step 1: Create Project Memory

Create .factory/memories.md in your project root:

# Project Memory

## Project Context
- **Name**: Acme Dashboard
- **Type**: B2B SaaS application
- **Stack**: Next.js 14, TypeScript, Prisma, PostgreSQL
- **Started**: January 2024

## Architecture Decisions

### 2024-01-15: Database Choice
**Decision**: PostgreSQL over MongoDB
**Reasoning**: Strong relational data model, ACID compliance needed for financial data
**Trade-offs**: More rigid schema, but better for reporting queries

### 2024-02-01: Authentication Approach
**Decision**: NextAuth.js with custom credentials provider
**Reasoning**: Need to integrate with existing enterprise LDAP
**Implementation**: See `src/lib/auth/` for setup

### 2024-02-20: State Management
**Decision**: Zustand for client state, React Query for server state
**Reasoning**: Simpler than Redux, better separation of concerns
**Pattern**: Store files in `src/stores/`, queries in `src/queries/`

## Known Technical Debt
- [ ] Auth refresh token logic needs refactoring (#234)
- [ ] Dashboard queries should be optimized with proper indexes
- [ ] Legacy API endpoints in `/api/v1/` need deprecation

## Domain Knowledge

### Business Rules
- Users belong to Organizations (multi-tenant)
- Subscription tiers: Free, Pro, Enterprise
- Free tier limited to 3 team members
- Data retention: 90 days for Free, unlimited for paid

### Key Entities
- `User`: Individual accounts, can belong to multiple orgs
- `Organization`: Tenant container, has subscription
- `Project`: Work container within an org
- `Task`: Work items within projects

## Team Conventions
- PR titles follow conventional commits
- All PRs need at least one approval
- Deploy to staging on merge to `develop`
- Deploy to production on merge to `main`

Step 2: Reference in Project AGENTS.md

Update your project’s AGENTS.md:

## Project Memory
Architecture decisions, domain knowledge, and project history are documented in `.factory/memories.md`.
Always check this file before making significant architectural or design decisions.

Memory Categories

Organize your memories into useful categories:

Preferences (Personal)

What you like and how you work:

## Preferences
- Code style choices
- Tool preferences  
- Communication style
- Learning style

Decisions (Project)

What was decided and why:

## Decisions
- Architecture choices with reasoning
- Library selections with trade-offs
- Design patterns adopted
- Standards agreed upon

Context (Project)

Background information:

## Context
- Business domain knowledge
- Key entities and relationships
- External integrations
- Performance requirements

History (Both)

What happened when:

## History
- Major refactors completed
- Migrations performed
- Issues resolved
- Lessons learned

Automatic Memory Capture

Create a hook that helps you capture memories as you work.

The “Remember This” Hook

When you say “remember this:” followed by content, automatically append to memories. You can trigger memory capture with either special characters or phrases. Choose based on your preference:

# prefix trigger
Phrase trigger

Trigger with # at the start of your message for quick capture.Usage:

“#we use the repository pattern”
“##I prefer early returns” (double ## for personal)

Create ~/.factory/hooks/memory-capture.py:

#!/usr/bin/env python3
"""Captures messages starting with # and appends to memories.md"""
import json, sys, os
from datetime import datetime

def main():
    try:
        data = json.load(sys.stdin)
        prompt = data.get('prompt', '').strip()
        
        if not prompt.startswith('#'):
            return
        
        # ## = personal, # = project
        if prompt.startswith('##'):
            content = prompt[2:].strip()
            mem_file = os.path.expanduser('~/.factory/memories.md')
        else:
            content = prompt[1:].strip()
            project_dir = os.environ.get('FACTORY_PROJECT_DIR', os.getcwd())
            project_factory = os.path.join(project_dir, '.factory')
            if os.path.exists(project_factory):
                mem_file = os.path.join(project_factory, 'memories.md')
            else:
                mem_file = os.path.expanduser('~/.factory/memories.md')
        
        if content:
            timestamp = datetime.now().strftime('%Y-%m-%d')
            with open(mem_file, 'a') as f:
                f.write(f"\n- [{timestamp}] {content}\n")
            
            print(json.dumps({'systemMessage': f'✓ Saved to {mem_file}'}))
    except:
        pass

if __name__ == '__main__':
    main()

Trigger with phrases like “remember this:”, “note:”, etc.Usage:

“Remember this: we use the repository pattern”
“Note: auth tokens expire after 24 hours”

Create ~/.factory/hooks/memory-capture.py:

#!/usr/bin/env python3
"""Captures 'remember this:' statements and appends to memories.md"""
import json, sys, os
from datetime import datetime

def main():
    try:
        data = json.load(sys.stdin)
        prompt = data.get('prompt', '')
        
        triggers = ['remember this:', 'remember:', 'note:', 'save this:']
        
        for trigger in triggers:
            if trigger in prompt.lower():
                idx = prompt.lower().index(trigger)
                content = prompt[idx + len(trigger):].strip()
                
                if content:
                    # Personal if specified, otherwise project
                    if 'personal' in prompt.lower():
                        mem_file = os.path.expanduser('~/.factory/memories.md')
                    else:
                        project_dir = os.environ.get('FACTORY_PROJECT_DIR', os.getcwd())
                        project_factory = os.path.join(project_dir, '.factory')
                        if os.path.exists(project_factory):
                            mem_file = os.path.join(project_factory, 'memories.md')
                        else:
                            mem_file = os.path.expanduser('~/.factory/memories.md')
                    
                    timestamp = datetime.now().strftime('%Y-%m-%d')
                    with open(mem_file, 'a') as f:
                        f.write(f"\n- [{timestamp}] {content}\n")
                    
                    print(json.dumps({'systemMessage': f'✓ Saved to {mem_file}'}))
                break
    except:
        pass

if __name__ == '__main__':
    main()

Make it executable and configure the hook:

chmod +x ~/.factory/hooks/memory-capture.py

Add to your hooks configuration via /hooks:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.factory/hooks/memory-capture.py"
          }
        ]
      }
    ]
  }
}

With # prefix:

“#we decided to use Zustand for state management”
“##I prefer early returns” (double ## saves to personal)

With phrase triggers:

“Remember this: we decided to use Zustand for state management”
“Note: the auth module uses JWT with 24-hour expiration”

Alternative: Memory Capture Skill

Instead of a hook, you can use a skill that Droid invokes when you ask to remember something. This gives you more interactive control over categorization. See the memory-capture skill example for a ready-to-use implementation.

Alternative: Custom Slash Command

For quick manual capture, create a custom slash command: Create ~/.factory/commands/remember.md:

---
description: Save a memory to your memories file
argument-hint: <what to remember>
---

Add this to my memories file (~/.factory/memories.md):

$ARGUMENTS

Format it appropriately based on whether it's a preference, decision, or learning. Include today's date.

Then use /remember we chose PostgreSQL for better ACID compliance to capture memories on demand.

Which approach to choose?

Hook — Best for automatic capture without extra steps
Skill — Best when you want Droid to help categorize and format
Slash Command — Best for quick manual capture with consistent formatting

Memory Maintenance

Keep your memories useful with regular maintenance.

Monthly Review Checklist

## Monthly Memory Review

### Personal Memory (~/.factory/memories.md)
- [ ] Remove outdated preferences (tools you no longer use)
- [ ] Update decisions that have changed
- [ ] Add new patterns you've adopted
- [ ] Archive old entries that are no longer relevant

### Project Memory (.factory/memories.md)
- [ ] Review architecture decisions - still valid?
- [ ] Update technical debt items
- [ ] Add new domain knowledge learned
- [ ] Document recent major changes

Archiving Old Memories

When memories become stale, move them to an archive:

# memories.md

## Current Decisions
[active decisions here]

## Archive (2023)
<details>
<summary>Archived decisions from 2023</summary>

### 2023-06: Original Auth System
**Decision**: Custom JWT implementation
**Status**: Replaced by NextAuth.js in 2024-02
**Reason for change**: Maintenance burden, security updates

</details>

Advanced: Memory-Aware Skills

Create skills that leverage your memory files:

---
name: context-aware-implementation
description: Implement features using project memory and conventions.
---

# Context-Aware Implementation

Before implementing any feature:

1. **Check project memory** (`.factory/memories.md`):
   - What architecture decisions apply?
   - What patterns should I follow?
   - What constraints exist?

2. **Check personal preferences** (`~/.factory/memories.md`):
   - What code style does the user prefer?
   - What tools should I use?

3. **Check rules** (`.factory/rules/`):
   - What conventions apply to this file type?
   - What testing requirements exist?

Then implement following all discovered context.

Quick Reference

File Locations

Memory Type	Location	Scope
Personal preferences	`~/.factory/memories.md`	All projects
Project decisions	`.factory/memories.md`	This project
Team conventions	`.factory/rules/*.md`	This project

When to Add Memories

Event	What to Record	Where
Made an architecture decision	Decision + reasoning	Project
Discovered a preference	What you prefer	Personal
Learned domain knowledge	Business rules, entities	Project
Changed your workflow	New tool or pattern	Personal
Resolved a tricky issue	Solution and context	Project

Memory Format Template

### [Date]: [Title]
**Decision/Preference**: [What]
**Reasoning**: [Why]
**Context**: [When this applies]
**Trade-offs**: [What you gave up]

Power User

Building

Skills

Hooks

Droid Exec (Headless)

The Memory System Architecture

Setting Up Personal Memory

Step 1: Create the Memory File

Step 2: Reference in AGENTS.md

Setting Up Project Memory

Step 1: Create Project Memory

Step 2: Reference in Project AGENTS.md

Memory Categories

Preferences (Personal)

Decisions (Project)

Context (Project)

History (Both)

Automatic Memory Capture

The “Remember This” Hook

Alternative: Memory Capture Skill

Alternative: Custom Slash Command

Memory Maintenance

Monthly Review Checklist

Archiving Old Memories

Advanced: Memory-Aware Skills

Quick Reference

File Locations

When to Add Memories

Memory Format Template

Next Steps

Setup Checklist

Rules Guide

Power User

Building

Skills

Hooks

Droid Exec (Headless)

​The Memory System Architecture

​Setting Up Personal Memory

​Step 1: Create the Memory File

​Step 2: Reference in AGENTS.md

​Setting Up Project Memory

​Step 1: Create Project Memory

​Step 2: Reference in Project AGENTS.md

​Memory Categories

​Preferences (Personal)

​Decisions (Project)

​Context (Project)

​History (Both)

​Automatic Memory Capture

​The “Remember This” Hook

​Alternative: Memory Capture Skill

​Alternative: Custom Slash Command

​Memory Maintenance

​Monthly Review Checklist

​Archiving Old Memories

​Advanced: Memory-Aware Skills

​Quick Reference

​File Locations

​When to Add Memories

​Memory Format Template

​Next Steps

Setup Checklist

Rules Guide

The Memory System Architecture

Setting Up Personal Memory

Step 1: Create the Memory File

Step 2: Reference in AGENTS.md

Setting Up Project Memory

Step 1: Create Project Memory

Step 2: Reference in Project AGENTS.md

Memory Categories

Preferences (Personal)

Decisions (Project)

Context (Project)

History (Both)

Automatic Memory Capture

The “Remember This” Hook

Alternative: Memory Capture Skill

Alternative: Custom Slash Command

Memory Maintenance

Monthly Review Checklist

Archiving Old Memories

Advanced: Memory-Aware Skills

Quick Reference

File Locations

When to Add Memories

Memory Format Template

Next Steps