Memory & Persistence

The Memory & Persistence system in Autohand CLI is designed to provide long-term statefulness, project-specific knowledge retention, and session continuity. It allows the agent to learn from past interactions, avoid repeating failed technical approaches, and maintain user preferences across different workspaces.

The system is bifurcated into two primary layers: Memory, which handles explicit facts and user-defined preferences, and Persistence, which manages session history, project-level metadata, and historical retrieval of successes and failures. This architecture ensures that the agent evolves with the project rather than starting from zero in every new session.

Sources: src/core/agent.ts:162-167, prd/historical-retrieval.md:10-25, prd/session-persistence.md:12-20

Memory Management Architecture

The MemoryManager is the core component responsible for storing and retrieving discrete "memories"—short, self-contained facts or preferences. It operates at two distinct levels: User and Project.

Memory Levels and Storage

Sources: src/memory/MemoryManager.ts:18-24, src/commands/memory.ts:27-42

Component Interaction

The following diagram illustrates how the MemoryManager interacts with the agent and the filesystem to persist and recall information.

The MemoryManager utilizes a Jaccard similarity threshold (defaulting to 0.6) to detect duplicate or similar memories before storing new ones, preventing data redundancy.

Sources: src/memory/MemoryManager.ts:12-55, src/core/agent.ts:602-635

Session Persistence

The Session Persistence system ensures that conversation history is maintained across CLI invocations. It captures user messages, assistant responses, and tool outputs in a durable format.

Session Lifecycle

The lifecycle involves automatic initialization, continuous message appending, and a finalization step that generates a session summary.

Sessions are stored using a unique ID format: YYYY-MM-DD_<short-hash>. The conversation.jsonl file uses an append-only format to ensure performance during long-running interactions.

Sources: prd/session-persistence.md:46-65, src/core/agent.ts:805-830

Project Knowledge & Historical Retrieval

The ProjectManager handles "Historical Retrieval," a system that synthesizes knowledge from previous sessions to prevent repeating "Anti-Patterns" (failed attempts) and to encourage "Best Practices" (successful patterns).

Knowledge Synthesis Logic

When a tool call occurs, the system records the result. Successful operations increase the confidence score of a pattern, while failures are logged to a dedicated failures.jsonl file for future duplicate detection.

Sources: src/session/ProjectManager.ts:36-65, prd/historical-retrieval.md:78-105

Similarity Matching for Failures

Before executing a command, the agent checks for similar past failures using a scoring algorithm.

Similarity scoring is weighted based on the tool type (+0.3), command/path fuzzy matching (+0.4), and context/tags (+0.3).

Sources: src/session/ProjectManager.ts:88-125, prd/historical-retrieval.md:118-135

Data Models

Memory Entry

The system stores memories as individual JSON files accompanied by a central index for fast lookup.

// Sources: src/memory/MemoryManager.ts:56-65
interface MemoryEntry {
  id: string;
  content: string;
  createdAt: string;
  updatedAt: string;
  tags?: string[];
  source?: string;
}

Project Knowledge

The knowledge.json file represents the synthesized intelligence of a project workspace.

{
  "updatedAt": "2025-11-19T14:32:00Z",
  "summary": "React + TypeScript app with FastAPI backend.",
  "antiPatterns": [
    {
      "pattern": "npm install redis-node",
      "reason": "Package doesn't exist, use ioredis",
      "occurredAt": "2025-11-18T15:30:00Z"
    }
  ],
  "bestPractices": []
}

Sources: prd/historical-retrieval.md:94-110, src/session/ProjectManager.ts:133-145

Core Functions & API

MemoryManager.ts

• store(content, level): Checks for similarity and saves a new memory. Lines 45-76
• findSimilar(content, level): Iterates through entries to find the highest similarity match. Lines 131-143
• getContextMemories(): Formats top 10 project and user memories for LLM injection. Lines 172-192

ProjectManager.ts

• recordFailure(projectPath, failure): Appends failure data and triggers knowledge synthesis. Lines 57-64
• isDuplicateFailure(projectPath, toolType, command): Prevents the agent from repeating high-similarity errors. Lines 82-101
• getKnowledge(projectPath): Retrieves the synthesized knowledge.json for a project. Lines 71-80

AutohandAgent (agent.ts)

• injectProjectKnowledge(): Injects synthesized best practices and anti-patterns into the active conversation. Lines 1590-1615
• handleMemoryStore(content): Interactive flow for the # command to save memories. Lines 602-646

Summary

The Memory & Persistence system transforms Autohand CLI from a stateless tool into a continuous engineering assistant. By persisting conversation history through the SessionManager, managing facts via MemoryManager, and synthesizing historical outcomes via ProjectManager, the architecture ensures that technical context and user preferences are preserved across the entire project lifecycle.