Docs

Memory & Channels

Agentastic's memory system creates a personalized AI experience by learning from your interactions and organizing knowledge into contextual channels. This powerful feature enables truly intelligent assistance that improves over time.

Understanding Memory

The memory system allows Agentastic to:

  • Remember previous conversations and contexts
  • Learn your preferences and patterns
  • Personalize responses to your style
  • Maintain continuity across sessions
  • Organize knowledge by topic or project

How Memory Works

Automatic Learning

When memory is enabled, Agentastic:

  1. Observes your interactions
  2. Identifies important information
  3. Stores relevant context
  4. Builds preference profiles
  5. Applies learning to future responses

Privacy-First Design

  • All memory stored locally by default
  • You control what's remembered
  • Clear memory anytime
  • Export or delete your data
  • No training on your data

Channels Overview

Channels organize memories into logical groups, similar to folders for your thoughts. Each channel can have different settings and retention policies.

Default Channels

General Channel

  • Catches all interactions not assigned elsewhere
  • Broad context learning
  • Default 30-day retention
  • Good for everyday use

Work Channel

  • Professional contexts
  • Project-specific information
  • Extended retention options
  • Formal communication style

Personal Channel

  • Casual interactions
  • Personal preferences
  • Private information
  • Relaxed communication style

Creating Custom Channels

Via Settings

  1. Open Settings → Memory
  2. Click "New Channel"
  3. Configure:
    • Name and description
    • Keywords for auto-routing
    • Retention period
    • Privacy level

Via YAML Configuration

channels:
  - name: project_phoenix
    description: Phoenix mobile app development
    keywords: 
      - phoenix
      - mobile app
      - iOS development
    retention: 90d
    auto_archive: true
    
  - name: blog_writing
    description: Blog content and ideas
    keywords:
      - blog
      - article
      - writing
    retention: 365d
    style: creative

Channel Configuration

Basic Settings

Channel Name

  • Unique identifier
  • Use descriptive names
  • Lowercase recommended
  • No spaces (use underscores)

Keywords

Auto-route conversations containing:

keywords:
  - project_name
  - client_name
  - specific_terms
  - @tags

Retention Policies

  • 7d - One week
  • 30d - One month (default)
  • 90d - Three months
  • 365d - One year
  • forever - No expiration

Advanced Settings

Auto-Routing Rules

routing_rules:
  - if_contains: ["bug", "error", "issue"]
    route_to: debugging_channel
  - if_matches: "^@client"
    route_to: client_work
  - if_app: "Xcode"
    route_to: development

Style Preferences

style_preferences:
  tone: professional
  verbosity: concise
  formatting: markdown
  language: en-US

Learning Weights

learning:
  writing_style: 0.8
  technical_terms: 1.0
  preferences: 0.9
  corrections: 1.0

Using Memory with Commands

Enable Memory for Query

@memory What did we discuss about the database schema?
@memory @email Use my standard greeting for clients
@memory Continue our conversation from yesterday

Specify Channel

@memory:work Find our discussion about Q4 goals
@memory:personal What restaurants did I mention liking?
@memory:project_x Show all decisions made this week

Memory Operations

@memory:clear Clear all memories
@memory:export Export channel data
@memory:stats Show memory usage
@memory:search Find specific memories

Memory in Action

Example: Project Context

Day 1: "Working on user authentication for Phoenix app"
Day 3: "Need to add 2FA to the login flow"
Day 5: @memory "What's the status of authentication?"

AI Response: "Based on our previous discussions, you're working on 
user authentication for the Phoenix app, with 2FA being the next 
feature to implement in the login flow."

Example: Writing Style

Multiple interactions where you correct:
"Let's do this" → "Let us proceed with this"

Future @email responses automatically use formal style

Example: Technical Preferences

Consistently use React hooks in code examples

@code automatically generates hook-based components

Channel Management

Switching Channels

@channel:work Switch to work context
@channel:personal Personal mode
@channel:auto Let AI decide

Channel Analytics

View in Settings → Memory:

  • Messages per channel
  • Storage usage
  • Most active times
  • Learning progress

Merging Channels

Combine related channels:

  1. Select source channels
  2. Choose merge strategy
  3. Create new combined channel
  4. Archive old channels

Protecting Memory Content

Permanent Instructions

You can protect critical instructions in memory files from being modified by the AI using permanent instruction tags. This ensures important directives remain unchanged even as the AI learns and updates other parts of your memory.

How It Works

Wrap any content you want to protect with <permanent_instruction> tags:

<permanent_instruction>
Your critical instructions here
These will never be modified by the AI
</permanent_instruction>

Key Features

  • Tag Syntax: Use <permanent_instruction> and </permanent_instruction> tags
  • Case Insensitive: Tags work with any capitalization (e.g., <PERMANENT_INSTRUCTION>)
  • Multiple Blocks: You can have multiple protected sections in a single file
  • Placement: Tags can appear anywhere in the file - top, middle, or end
  • AI Visibility: The AI can read protected content but cannot modify or delete it
  • Error Handling: If the AI attempts to modify protected content, it receives a clear error

Example: Fitness Coaching

# Fitness Memory (agent.md)

<permanent_instruction>
Coaching Style Guidelines:
- Always be encouraging and supportive
- Never recommend exercises that strain knees
- Target goal: Run 10K by December 2025
- Preferred workout time: Early mornings
</permanent_instruction>

## Recent Progress
- October 15: Completed 5K run in 35 minutes
- October 18: Morning jog - 3 miles
- Current pace: 7:30/mile average

## Weekly Plan
- Monday: Rest day
- Tuesday: Interval training

The AI can freely update "Recent Progress" and "Weekly Plan" sections, but the coaching guidelines remain constant.

Example: Project Context

# Project Phoenix Memory

<permanent_instruction>
Project: Phoenix Mobile App
Tech Stack: React Native, Node.js, PostgreSQL
API Endpoint: https://api.phoenix.internal
Deployment: Always use staging before production
Code Review: Required for all PRs
</permanent_instruction>

## Current Sprint (Week 12)
- Implementing user authentication
- Adding 2FA support
- Testing OAuth integration

## Decisions Made
- Using JWT for session management (Oct 10)
- Selected Auth0 for OAuth provider (Oct 12)

Example: Writing Style Preferences

# Writing Style (user.md)

<permanent_instruction>
Communication Preferences:
- Tone: Professional but approachable
- Avoid: Jargon, buzzwords, excessive formality
- Include: Clear examples, bullet points
- Format: Use Markdown headings and lists
- Length: Concise responses unless depth is requested
</permanent_instruction>

Protected Files

  • user.md: This file is completely read-only for the AI - no modifications allowed at all
  • Other memory files: Can be edited, but respect <permanent_instruction> tags

Use Cases

Project Guidelines

<permanent_instruction>
Code Style:
- Use TypeScript strict mode
- Follow Airbnb style guide
- Maximum file length: 300 lines
- Always write unit tests
</permanent_instruction>

Personal Boundaries

<permanent_instruction>
Privacy Rules:
- Never share personal email addresses
- Keep work and personal contexts separate
- Don't include family details in work contexts
</permanent_instruction>

Domain Knowledge

<permanent_instruction>
Industry Terminology:
- "Client" always refers to mobile app, not customers
- "Platform" means backend API infrastructure
- "Release" requires QA approval + docs update
</permanent_instruction>

Technical Details

  • Tag Format: Only top-level tags are recognized (nested tags are not supported)
  • Content Type: Any text content between tags is protected
  • Preservation: Content is preserved character-for-character, including whitespace
  • Modification Detection: Any change to protected content triggers an error
  • File Location: Memory files are in ~/Library/Application Support/agentastic/memory/ (macOS)

Best Practices

  1. Use Sparingly: Only protect truly critical, unchanging information
  2. Be Clear: Protected instructions should be specific and actionable
  3. Review Regularly: Occasionally check if protected content is still relevant
  4. Combine with user.md: Put the most critical information in user.md (fully read-only)
  5. Document Purpose: Add comments explaining why content is protected

Privacy and Control

What's Remembered

  • Conversation content
  • Corrections you make
  • Stated preferences
  • Frequently used patterns

What's NOT Remembered

  • Passwords or secrets
  • Credit card information
  • Private API keys
  • Sensitive personal data

Memory Controls

@memory:pause Temporarily disable
@memory:resume Re-enable memory
@memory:private Don't save this conversation
@memory:delete Remove specific memory

Best Practices

Channel Organization

  1. By Project - One channel per major project
  2. By Context - Work, personal, hobbies
  3. By Time - Quarterly channels for archiving
  4. By Importance - Priority channels with longer retention

Optimal Configuration

# Balanced configuration
channels:
  default:
    retention: 30d
    auto_archive: true
    learn_style: true
    
  important:
    retention: forever
    backup: true
    encryption: true

Memory Hygiene

  • Review channels monthly
  • Archive completed projects
  • Export important data
  • Clear irrelevant memories

Advanced Memory Features

Cross-Channel Learning

global_learning:
  writing_style: true
  technical_vocab: true
  preferences: false  # Keep channel-specific

Memory Templates

templates:
  meeting_memory:
    capture: [decisions, action_items, participants]
    retention: 90d
    share_with: team_channel

Conditional Memory

conditions:
  - if_tagged: "#important"
    retention: forever
  - if_contains: "password"
    memory: false

Troubleshooting

Memory Not Working

  1. Check if enabled globally
  2. Verify channel is active
  3. Ensure keywords match
  4. Check retention hasn't expired

Wrong Channel Assignment

  1. Review keyword conflicts
  2. Check routing rules
  3. Use explicit channel tags
  4. Adjust priorities

Performance Issues

  1. Archive old channels
  2. Reduce retention periods
  3. Clear large memories
  4. Optimize keywords

Integration Examples

With Text Expansion

expansion:
  trigger: "statusupdate"
  content: "@memory:project_x Generate status from this week's progress"

With AI Commands

@agent @memory Research continuation of last week's analysis
@search @memory:blog Find sources we've used before

With Workflows

workflow:
  daily_standup:
    - memory: yesterday's tasks
    - memory: today's plans
    - generate: standup update

Next Steps

The memory system transforms Agentastic from a tool into an intelligent partner that truly understands your needs. Start with simple channels and gradually build your personalized AI assistant!