> ## Documentation Index > Fetch the complete documentation index at: https://docs.factory.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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](/web/getting-started/overview)—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`: ```markdown theme={null} # 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`: ```markdown theme={null} ## 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: ```markdown theme={null} # 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`: ```markdown theme={null} ## 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: ```markdown theme={null} ## Preferences - Code style choices - Tool preferences - Communication style - Learning style ``` ### Decisions (Project) What was decided and why: ```markdown theme={null} ## Decisions - Architecture choices with reasoning - Library selections with trade-offs - Design patterns adopted - Standards agreed upon ``` ### Context (Project) Background information: ```markdown theme={null} ## Context - Business domain knowledge - Key entities and relationships - External integrations - Performance requirements ``` ### History (Both) What happened when: ```markdown theme={null} ## 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: 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`: ```python theme={null} #!/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`: ```python theme={null} #!/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: ```bash theme={null} chmod +x ~/.factory/hooks/memory-capture.py ``` Add to your hooks configuration via `/hooks`: ```json theme={null} { "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](/cli/configuration/skills) 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](/cli/configuration/custom-slash-commands): Create `~/.factory/commands/remember.md`: ```markdown theme={null} --- description: Save a memory to your memories file argument-hint: --- 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 ```markdown theme={null} ## 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: ```markdown theme={null} # memories.md ## Current Decisions [active decisions here] ## Archive (2023)
Archived decisions from 2023 ### 2023-06: Original Auth System **Decision**: Custom JWT implementation **Status**: Replaced by NextAuth.js in 2024-02 **Reason for change**: Maintenance burden, security updates
``` *** ## Advanced: Memory-Aware Skills Create skills that leverage your memory files: ```markdown theme={null} --- 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 ```markdown theme={null} ### [Date]: [Title] **Decision/Preference**: [What] **Reasoning**: [Why] **Context**: [When this applies] **Trade-offs**: [What you gave up] ``` *** ## Next Steps Complete power user configuration Organize team conventions