#Memory

Persistent memory lets a session record what worked (and what didn't) and pull those facts back later. Every SDK session has a file-backed store at <workspace>/.a3s/memory, or at the ACL memory_dir when that is set. Pass a memoryStore / memory_store (with_file_memory in Rust, FileMemoryDir in Go) only when you want a different path or backend; a relative path resolves against the process working directory. Write outcomes explicitly with rememberSuccess / rememberFailure, then retrieve them with recallSimilar, recallByTags, or memoryRecent.

LLM extraction is also on by default (llm_extraction in the ACL memory block). After each completed turn with a non-empty prompt and reply, the session asks the model to distill durable memories: at most 5 items per turn, from at most 8,000 characters of input. Closing the session waits, up to a timeout, for extractions already in progress. Default stores merge an exact duplicate (the same content ignoring case and whitespace, at least 24 characters long) into the existing item; every other memory is stored separately.

use a3s_code_core::{Agent, SessionOptions};

#[tokio::main]
async fn main() -> a3s_code_core::Result<()> {
    let agent = Agent::new("agent.acl").await?;
    let session = agent
        .session_builder("/repo")
        .options(SessionOptions::new().with_file_memory("./.a3s/memory"))
        .build()
        .await?;
    let memory = session.memory().expect("memory is configured");

    memory
        .remember_success(
            "refactored auth module",
            &["read".into(), "edit".into(), "bash".into()],
            "all tests passed after extracting AuthService",
        )
        .await?;
    memory
        .remember_failure(
            "migration attempt",
            "psql connection refused on port 5432",
            &["bash".into()],
        )
        .await?;

    let recent = memory.get_recent(10).await?;
    let by_tags = memory
        .recall_by_tags(&["read".into(), "edit".into()], 5)
        .await?;
    let similar = memory.recall_similar("auth refactor", 5).await?;
    println!("{} {} {}", recent.len(), by_tags.len(), similar.len());

    session.close().await;
    agent.close().await;
    Ok(())
}

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

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

// Record outcomes as the agent works.
await session.rememberSuccess(
  'refactored auth module',
  ['read', 'edit', 'bash'],
  'all tests passed after extracting AuthService',
);
await session.rememberFailure(
  'migration attempt',
  'psql connection refused on port 5432',
  ['bash'],
);

// Recall later — by recency, by tool tags, or by text similarity.
const recent = await session.memoryRecent(10);
const byTags = await session.recallByTags(['read', 'edit'], 5);
const similar = await session.recallSimilar('auth refactor', 5);

console.log(recent.length, byTags.length, similar.length);

await session.closeAsync();
await agent.close();

from a3s_code import Agent, SessionOptions, FileMemoryStore

agent = Agent.create("agent.acl")
opts = SessionOptions()
opts.memory_store = FileMemoryStore("./.a3s/memory")
session = agent.session("/repo", opts)

# Record outcomes as the agent works. Python helpers are synchronous — no await.
session.remember_success(
    "refactored auth module",
    ["read", "edit", "bash"],
    "all tests passed after extracting AuthService",
)
session.remember_failure(
    "migration attempt",
    "psql connection refused on port 5432",
    ["bash"],
)

# Recall later — by recency, by tool tags, or by text similarity.
recent = session.memory_recent(10)
by_tags = session.recall_by_tags(["read", "edit"], 5)
similar = session.recall_similar("auth refactor", 5)

print(len(recent), len(by_tags), len(similar))

session.close()
agent.close()

package main

import (
	"context"
	"fmt"
	"log"

	code "github.com/A3S-Lab/Code/sdk/go/v9"
)

func main() {
	ctx := context.Background()
	agent, err := code.Create(ctx, "agent.acl")
	if err != nil {
		log.Fatal(err)
	}
	defer agent.Close(context.Background())
	options := &code.SessionOptions{FileMemoryDir: "./.a3s/memory"}

	first, err := agent.Session(ctx, "/repo", options)
	if err != nil {
		log.Fatal(err)
	}
	if err := first.RememberSuccess(
		ctx,
		"auth verification rule",
		[]string{"cargo", "test"},
		"Authentication changes must pass cargo test.",
	); err != nil {
		log.Fatal(err)
	}
	if err := first.Close(ctx); err != nil {
		log.Fatal(err)
	}

	second, err := agent.Session(ctx, "/repo", options)
	if err != nil {
		log.Fatal(err)
	}
	defer second.Close(context.Background())
	items, err := second.RecallSimilar(
		ctx,
		"verification required for authentication changes",
		5,
	)
	if err != nil {
		log.Fatal(err)
	}
	for _, item := range items {
		fmt.Println(item.Content)
	}
}

All four SDKs expose explicit memory write/query helpers. In Go these are RememberSuccess, RememberFailure, RecallSimilar, RecallByTags, MemoryRecent, and the working/short-term memory methods. rememberSuccess takes a short task description, the tools involved (also used as tags), and the outcome text; rememberFailure takes the task, the error text, and then the tools. recallByTags returns items carrying any of the given tags. The default stores rank recallSimilar results by matching the query's terms against each item's content and tags, weighted by importance and recency. If the memory store cannot be created, session creation fails with a session-initialization error that names the store path.