How to Configure Agent Memory in PrimeAgent: A Complete Guide to Persistence and Scope

Configure PrimeAgent memory by setting a storage directory via CLI flag or environment variable, then manage entries through the harness API with global or local scope.

PrimeAgent's memory system lets agents retain facts, user preferences, and operational notes across sessions. This guide walks through the configuration options, directory structure, and runtime API based on the source code in PrimeIntellect-ai/prime-agent.

What Is Agent Memory in PrimeAgent

Agent memory consists of durable entries that the model can retrieve and update during execution. Each memory entry follows a strict TypeScript interface defined in packages/coding-agent/src/core/harness.ts:

interface MemoryEntry {
  id: string;                    // unique identifier
  kind: "memory";                // type discriminant
  title: string;                 // human-readable label
  content: string;               // the stored information
  scope?: "global" | "local";    // persistence boundary
}

Memories persist as JSON files on disk and load into the harness state at startup. The harness exposes methods to create, read, update, and delete entries during agent execution.

Setting the Memory Directory

PrimeAgent determines where to store memory files through two configuration mechanisms in packages/coding-agent/src/cli/args.ts and packages/coding-agent/src/env.ts.

CLI Flag Method

Pass the --memory-dir flag when launching the agent:

prime-agent --memory-dir /path/to/memory/store

Environment Variable Method

Set PRIME_AGENT_MEMORY_DIR before starting the agent:

export PRIME_AGENT_MEMORY_DIR=/path/to/memory/store
prime-agent

Default Location

If neither is provided, PrimeAgent defaults to a hidden directory in the user's home folder:

const DEFAULT_MEMORY_DIR = path.join(os.homedir(), ".prime-agent");

This logic resides in packages/coding-agent/src/env.ts.

Understanding Memory Scope

PrimeAgent supports two persistence scopes configured per memory entry:

• Global scope — scope: "global" — persists across all agent sessions, stored under <memory-dir>/global/memory/
• Local scope — scope: "local" — tied to a specific session, stored under <memory-dir>/local/memory/

The loadHarnessState(dir, scope) function in packages/coding-agent/src/core/harness.ts reads the appropriate subdirectory based on this parameter. Choose global for user preferences and long-term knowledge; use local for temporary context that should not leak between sessions.

Directory Structure and File Layout

A configured memory directory organizes entries by scope and type:

<memory-dir>/
├── global/
│   └── memory/
│       ├── user_preferences.json
│       ├── project_context.json
│       └── ...          # one JSON file per memory entry

└── local/
    └── memory/
        ├── session_notes.json
        └── ...          # session-specific entries

Each .json file contains a single serialized MemoryEntry object. The harness loads these on startup and writes updates immediately to maintain durability.

Runtime Memory Operations

Once running, agents interact with memory through the harness API exposed via rlm.harness. Test code in packages/coding-agent/test/system-prompt.test.ts (lines 79-87) demonstrates the available methods.

Creating a Memory Entry

await rlm.harness.create_memory({
  id: "user_name_preference",
  title: "User Name",
  content: "User prefers to be addressed as 'Alex'",
  scope: "global",
});

Updating an Existing Memory

await rlm.harness.update_memory("user_name_preference", {
  content: "User prefers to be addressed as 'Alexandra'",
});

Deleting a Memory

await rlm.harness.delete_memory("user_name_preference");

Reading Memories

Access the current memory map directly through the harness entries:

const memories = rlm.harness.entries.memory;
const memoryList = Object.values(memories).map(
  m => `${m.title}: ${m.content}`
);
console.log(memoryList);

Complete Configuration Example

This startup script demonstrates full memory configuration with directory setup and initial population:

#!/bin/bash

# Create custom memory directory

mkdir -p /var/prime-agent/global/memory

# Start agent with explicit memory directory

PRIME_AGENT_MEMORY_DIR=/var/prime-agent prime-agent --memory-dir /var/prime-agent

From within an agent session, populate foundational memories:

// Store persistent user context
await rlm.harness.create_memory({
  id: "project_stack",
  title: "Technology Stack",
  content: "Node.js 20, TypeScript, PostgreSQL 15 with Prisma ORM",
  scope: "global",
});

// Store session-specific task context
await rlm.harness.create_memory({
  id: "current_sprint",
  title: "Sprint Goal",
  content: "Complete user authentication module by Friday",
  scope: "local",
});

Key Source Files and Functions

File	Purpose
packages/coding-agent/src/core/harness.ts	Core harness implementation with loadHarnessState(), createMemory(), updateMemory(), deleteMemory()
packages/coding-agent/src/cli/args.ts	CLI argument parsing including --memory-dir
packages/coding-agent/src/env.ts	Environment variable handling for PRIME_AGENT_MEMORY_DIR
packages/coding-agent/test/system-prompt.test.ts	Runtime API usage examples (lines 79-87)

Summary

• Memory directory is set via --memory-dir flag or PRIME_AGENT_MEMORY_DIR environment variable, defaulting to ~/.prime-agent
• Scope determines persistence: global for cross-session storage, local for session-bound entries
• Physical storage uses JSON files organized under <memory-dir>/{global,local}/memory/
• Runtime API exposed through rlm.harness provides create_memory, update_memory, delete_memory, and direct entries.memory access
• Immediate durability writes changes to disk on every mutation operation

Frequently Asked Questions

How do I migrate memories between different PrimeAgent installations?

Copy the entire memory directory structure to the new location. Each JSON file represents one entry, so you can selectively transfer global/memory/ contents for cross-machine persistence or local/memory/ for session-specific context.

Can multiple agent instances share the same memory directory?

Yes, but concurrent writes risk corruption. PrimeAgent does not implement file locking in the current implementation at packages/coding-agent/src/core/harness.ts. For production deployments, use separate directories per instance or implement external synchronization.

What happens if I delete a memory file while PrimeAgent is running?

The harness maintains an in-memory cache. Deleted files reappear if the agent writes to that memory ID again. Restart the agent to synchronize with the current disk state via loadHarnessState() in packages/coding-agent/src/core/harness.ts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}