Memory

A3S Code uses a two-layer memory architecture. The storage layer (a3s-memory) owns the MemoryStore trait and its default implementations. The agent layer (a3s-code) owns the three-tier session memory (AgentMemory) and context injection (MemoryContextProvider).

a3s-memory                          a3s-code
──────────────────────────────      ──────────────────────────────
MemoryStore (trait)                 AgentMemory
InMemoryStore                         ├── working    (Vec, max 10)
FileMemoryStore                       ├── short_term (VecDeque, max 100)
MemoryItem                            └── long_term  (→ MemoryStore)
MemoryType
RelevanceConfig                     MemoryConfig
                                    MemoryContextProvider

This separation means you can swap the storage backend without touching any agent code.

Quick Start

import { Agent, FileMemoryStore } from '@a3s-lab/code';

const agent = await Agent.create('agent.hcl');
const session = agent.session('.', {
  memoryStore: new FileMemoryStore('./memory'),
});

const result = await session.send('Remember: this project deploys to AWS us-east-1');

from a3s_code import Agent, SessionOptions, FileMemoryStore

agent = Agent.create("agent.hcl")
session = agent.session(".", SessionOptions(
    memory_store=FileMemoryStore("./memory"),
))

result = session.send("Remember: this project deploys to AWS us-east-1")

Memory Types

Failures are stored as Episodic with importance 0.9 — higher than successes so the agent avoids repeating them.

Three-Tier Session Memory

Working memory   — active context, auto-trimmed by relevance when over capacity (max 10)
Short-term       — current session, FIFO trim when over capacity (max 100)
Long-term        — persisted via MemoryStore, survives session restarts

remember() writes to both long-term and short-term simultaneously.

MemoryItem

Every memory is a MemoryItem. The builder API makes construction ergonomic:

Relevance Scoring

When the agent needs context, memories are ranked by a score that combines importance and recency:

score = importance × importance_weight + exp(−age_days / decay_days) × recency_weight

Default config: importance_weight = 0.7, recency_weight = 0.3, decay_days = 30.

Configure via HCL:

memory {
  relevance {
    decay_days        = 30.0
    importance_weight = 0.7
    recency_weight    = 0.3
  }
  max_short_term = 100
  max_working    = 10
}

Storage Backends

FileMemoryStore

The default persistent backend. One JSON file per item, plus a compact index for fast search:

memory/
  index.json          ← lightweight index (id, tags, importance, timestamp)
  items/
    {uuid}.json       ← full item content, written atomically

Key properties:

• Atomic writes via .tmp → rename — no corruption on crash
• Index loaded into memory on init for fast recallSimilar() and recallByTags()
• Path traversal prevention on memory IDs
• rebuild_index() recovers from index corruption by scanning item files

Custom Backend (Rust SDK)

Implement MemoryStore to use any storage system — SQLite, Redis, a vector DB:

FileMemoryStore uses substring matching for search. A vector store replaces this with semantic similarity — no other changes needed.

Context Injection

MemoryContextProvider is registered automatically when memory is active. On each turn:

1. Retrieves up to 5 relevant memories by substring match against the current prompt
2. Injects them into the system prompt as structured context blocks
3. After turn completion, stores the interaction as a Procedural memory

System Prompt
├── Base instructions
├── [memory] User prefers TypeScript           ← MemoryContextProvider
├── [memory] Deploy via `just release`         ← MemoryContextProvider
├── [resource] Related code snippets           ← FileSystemContextProvider
└── Tool definitions

Events

API Reference

SessionOptions

MemoryStore trait