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

> Configure PrimeAgent memory persistence and scope easily. Learn to set storage directories and manage entries using the harness API for global or local scope. Get the complete guide now.

- Repository: [Prime Intellect/prime-agent](https://github.com/PrimeIntellect-ai/prime-agent)
- Tags: how-to-guide
- Published: 2026-08-14

---

**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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/harness.ts):

```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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/cli/args.ts) and [`packages/coding-agent/src/env.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/env.ts).

### CLI Flag Method

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

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

```

### Environment Variable Method

Set `PRIME_AGENT_MEMORY_DIR` before starting the agent:

```bash
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:

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

```

This logic resides in [`packages/coding-agent/src/env.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/test/system-prompt.test.ts) (lines 79-87) demonstrates the available methods.

### Creating a Memory Entry

```ts
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

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

```

### Deleting a Memory

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

```

### Reading Memories

Access the current memory map directly through the harness entries:

```ts
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:

```bash
#!/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:

```ts
// 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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/harness.ts) | Core harness implementation with `loadHarnessState()`, `createMemory()`, `updateMemory()`, `deleteMemory()` |
| [`packages/coding-agent/src/cli/args.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/cli/args.ts) | CLI argument parsing including `--memory-dir` |
| [`packages/coding-agent/src/env.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/env.ts) | Environment variable handling for `PRIME_AGENT_MEMORY_DIR` |
| [`packages/coding-agent/test/system-prompt.test.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/harness.ts).