Built-in Memory API¶

Note

Alpha. The built-in memory API is backed by the Agent Memory Server (AMS). Provision it with abi-core add service agent-memory — works for a standalone agent or an ABI Swarm project alike. It is under active development and the API may change between releases.

The previous page covered conversation memory — the LLM remembering messages in a thread. This page covers the built-in memory API: explicit functions to store and recall information across steps, tasks, and sessions, backed by the Agent Memory Server (AMS).

Two kinds of memory¶

	Conversation memory (`thread_id`)	Built-in memory API (AMS)
Scope	One agent’s LLM thread	System-wide, shared across agents
Persistence	In-process (lost on restart)	Redis-backed (survives restarts)
Control	Implicit (LLM sees history)	Explicit (you choose what to store)
Types	Conversation only	Short-term + long-term semantic

Use conversation memory for chat continuity. Use the built-in API when you need to deliberately save a result, a decision, or a piece of state and recall it later — possibly from a different agent.

Short-term vs long-term¶

Short-term (working) memory — scoped to a session (context_id). Holds the current task’s context: intermediate results, pending state. Think “scratchpad for this session”.
Long-term memory — persistent and searched by semantic similarity. Holds facts, past results, preferences that should outlive a single session.

Requirements¶

The built-in memory API talks to the Agent Memory Server. Provision it with:

abi-core add service agent-memory

This works in any project — a single agent created with abi-core add agent, or a full ABI Swarm. It adds the AMS + Redis containers to compose.yaml and, if agents already exist in the project, retroactively wires AGENT_MEMORY_URL (and the matching depends_on) into each of them — no manual editing needed. Any agent added after the service exists gets it automatically too. Then run abi-core run (or docker compose up -d --build) to start it.

Agents receive two environment variables:

Variable	Purpose
`AGENT_MEMORY_URL`	AMS base URL, e.g. `http://my-project-agent-memory:8000`
`CONTEXT_ID`	Default session id used when you don’t pass one explicitly

If AGENT_MEMORY_URL is not set, every memory call degrades gracefully — writes return False, reads return "". Memory never blocks your agent.

See Environment Variables for the full AMS configuration.

Writing memory¶

Import the write functions from abi_core.agent and call them inside a step or task:

from abi_core.agent import add_short_term_memory, add_long_term_memory

@agent.step(name="process", input_map={"data": "$input.data", "context_id": "$input.context_id"})
async def process(data, context_id):
    result = do_work(data)

    # Short-term: remember within this session
    await add_short_term_memory(
        topic="processing",
        task="data_pipeline",
        content=f"Processed {len(data)} records, result={result}",
        context_id=context_id,
    )

    # Long-term: persist a fact for future sessions
    await add_long_term_memory(
        topic="user_preference",
        task="report_format",
        content="User prefers CSV exports over PDF",
        context_id=context_id,
    )
    return {"result": result}

Parameters¶

Both write functions share the same signature:

await add_short_term_memory(topic, task, content, context_id=None, memory_url=None) -> bool
await add_long_term_memory(topic, task, content, context_id=None, memory_url=None) -> bool

Parameter	Description
`topic`	A label for the memory (e.g. `"user_preference"`). Stored as a searchable topic.
`task`	The task/entity this memory is about (e.g. `"report_format"`). Stored as an entity.
`content`	The memory text.
`context_id`	Session id. Optional — falls back to the `CONTEXT_ID` env var.
`memory_url`	AMS URL. Optional — falls back to the `AGENT_MEMORY_URL` env var.

Both return True on success, False if memory is unavailable.

Reading memory¶

from abi_core.agent import (
    get_short_term_memory,
    get_long_term_memory,
    recall_memory_context,
)

# Get this session's working memory as text
recent = await get_short_term_memory(context_id=context_id)

# Semantic search over long-term memory
matches = await get_long_term_memory("report format preferences", limit=5)

# Hydrate a query with relevant memory (ready to inject into a system prompt)
context = await recall_memory_context("generate the quarterly report", context_id=context_id)

recall_memory_context is the most convenient for LLM calls — it combines session and long-term memory into a single block of context text you can prepend to your system prompt:

from abi_core.agent import invoke, recall_memory_context

memory = await recall_memory_context(query, context_id=context_id)
system_prompt = base_prompt
if memory:
    system_prompt = f"{base_prompt}\n\n## Relevant context:\n{memory}"

result = await invoke(config.LLM_CONFIG, query, system_prompt=system_prompt)

Letting the LLM recall memory (tools)¶

To let the LLM decide when to look something up, add the ready-made memory tools to your agent:

from abi_core.memory import MEMORY_TOOLS  # [get_long_term_memory, get_short_term_memory]

class MyAgent(AbiAgent):
    def __init__(self):
        super().__init__(
            agent_name="my-agent",
            llm_config=config.LLM_CONFIG,
            tools=[*MEMORY_TOOLS],  # add your own tools too
            system_prompt="...",
        )

The LLM can then call get_long_term_memory(query) or get_short_term_memory() on its own when it needs prior context. These tools resolve context_id and the AMS URL from the environment, so the model only supplies a query (or nothing).

Graceful degradation¶

Every memory operation is best-effort:

If the AMS is unreachable or agent-memory-client isn’t installed, writes return False and reads return "".
No exception is raised, so a memory outage never breaks a request.

This is intentional: memory is an enhancement, not a hard dependency. Your agent keeps working even when memory is down — it just loses continuity until the AMS recovers.

Next step¶

👉 Testing Agents