Memory and Context Management

Build persistent memory so Droid remembers your preferences, decisions, and project history across sessions.

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

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()

Phrase trigger

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.

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]

---

Next Steps

Setup Checklist

Complete power user configuration

Rules Guide

Organize team conventions