Persistent Memory across agent sessions (per workspace)

Feature Request: Persistent Memory Across Agent Sessions (Per Workspace)

Problem

In my experience since having fun and building in Pixel Agent, every time a new Pixel Agents session starts, the agent initializes with no retained context. Prior decisions, architectural discussions, research findings, and project-specific assumptions are lost between sessions.

For multi-session workflows — research, ongoing builds, long-running refactors — this forces repeated explanation of context that already exists. The result is friction and loss of continuity.

Current Behavior

• Opening Pixel Agents starts a fresh, stateless session.

• No memory persists across sessions within the same VS Code workspace.

• Context only exists while the terminal session is alive.

• Restarting VS Code or restoring a workspace loses all accumulated agent context.

Proposed Solution

Introduce per-workspace persistent memory that survives session restarts.

Claude Code already implements this model using a project-scoped MEMORY.md file located at: ~/.claude/projects/<hashed-project-path>/memory/MEMORY.md

The agent reads this file at session start and appends to it during use. Because it is written to disk, context survives:

• Terminal restarts

• VS Code restarts

• System reboots

Pixel Agents could either:

1. Integrate with Claude Code’s existing memory file (if using Claude CLI underneath),
   or
2. Implement a native persistent memory system scoped to each workspace.

Suggested Storage Locations

Storage matters for sure perhaps: <workspace-root>/MEMORY.md

<workspace-root>/.pixelagents/MEMORY.md

Architecture Overview

Current Architecture (Stateless)

stateDiagram-v2
    [*] --> VSCodeOpen: Workspace Opens
    
    VSCodeOpen --> PixelAgent: Initialize Session
    
    PixelAgent --> EphemeralContext: Load Context
    
    state EphemeralContext {
        [*] --> ConversationHistory
        [*] --> FileReferences
        [*] --> TemporaryState
        
        ConversationHistory --> RAM
        FileReferences --> RAM
        TemporaryState --> RAM
    }
    
    EphemeralContext --> UserExit: Session Active
    
    UserExit --> Destroyed: Exit VS Code
    
    state Destroyed {
        [*] --> NoPersistence
        [*] --> NoMemory
        [*] --> FreshStart
    }
    
    Destroyed --> [*]
    
    note right of Destroyed
        ❌ Stateless Architecture
        All context lost on exit
        No cross-session memory
    end note

Key Characteristics:

• Stateless (resets every session)
• Ephemeral (lives in RAM only)
• No cross-session memory
• ⚡ Fast startup (nothing to load)
• ❌ No learning between sessions

Proposed Architecture (Persistent Memory)

Proposed Architecture (Persistent Memory)

flowchart TD
    Start([VS Code Workspace Opens]) --> Init[Pixel Agent Session Start]
    
    Init --> Read[ Read MEMORY.md]
    Read --> Scope["Project Scoped Memory:<br/>• Previous conversations<br/>• Project decisions<br/>• File history"]
    
    Scope --> Hydrate[⚡ Hydrate Context]
    Hydrate --> Context["Restored Context:<br/>• Known state<br/>• Past decisions<br/>• Conversation history"]
    
    Context --> Active[ Active Session]
    
    Active --> Append[ Append Updates to MEMORY.md]
    
    Append --> Details["Continuous Writing:<br/>• New decisions<br/>• Conversation logs<br/>• Code changes<br/>• Project insights"]
    
    Details --> Exit([User Exits])
    
    Exit --> Save[ Final Save to MEMORY.md]
    
    Save -.->|Next Session| Start

Key Characteristics:

• ✅ Persistent (memory survives restarts)
• File-based (MEMORY.md in project)
• Continuous updates (appends during session)
• Context-aware (learns from history)
• Project-scoped (isolated per workspace)
• Human-readable (plain markdown)

Session Data Flow

On Session Start

stateDiagram-v2
    [*] --> SessionStart
    
    SessionStart --> LoadMemory: Load MEMORY.md
    
    state LoadMemory {
        [*] --> ReadFile
        ReadFile --> ParseMarkdown
        ParseMarkdown --> ExtractContext
    }
    
    LoadMemory --> HydrateContext: Hydrate Agent Context
    
    state HydrateContext {
        [*] --> RestoreState
        RestoreState --> LoadHistory
        LoadHistory --> BuildContext
        BuildContext --> Ready
    }
    
    HydrateContext --> BeginInteraction: Ready
    
    BeginInteraction --> [*]
    
    note right of HydrateContext
        Agent now has:
        • Past conversations
        • Project decisions
        • File history
        • Continuous context
    end note

During Session

flowchart TD
    Active([Active Session]) --> Events["Session Events:<br/>• New decisions made<br/>• Project context evolves<br/>• Code changes<br/>• User questions answered"]
    
    Events --> Capture[ Capture Updates]
    
    Capture --> Append[Append to MEMORY.md]
    
    Append --> Persist["Written to File:<br/>• Decision logs<br/>• Context updates<br/>• Conversation summaries<br/>• Project insights"]
    
    Persist --> Continue[Session Continues]
    
    Continue -.->|More Activity| Events

Suggested Implementation Options

Key Requirements

• Automatically read memory file on agent start
• Append session learnings incrementally
• Scope memory per workspace/project
• Store durable information (decisions, constraints, assumptions)
• Avoid storing transient chat noise
• Keep file human-readable (Markdown preferred)

Use Cases

• Multi-session research or build projects where context compounds
• Long-running architecture work
• Refactoring efforts spanning multiple days
• VS Code workspace restoration workflows
• AI-assisted engineering requiring continuity

Environment

• VS Code 1.96+
• Claude Code CLI
• macOS
• Windows
• WSL2

Quick Notey note here:

I think that this persistent memory transforms the pixel agents from a stateless assistant into a project-aware collaborator.

Without it, every restart resets accumulated reasoning (you all can check me on this if I am wrong, if so that is my bad then)

With it, sessions build coherently over time.

️Pixel Agent rocks

Thank you @pablodelucca for building such a fun and futuristic way to work — genuinely changes how coding and clauding feels. Excited to see where this goes.