ArchAstro Docs

Overview

ArchAstro provides two memory patterns for agents:

Thread-scoped memory — key-value storage tied to a specific conversation.
Long-term memory — durable memory that helps an agent recall useful information across conversations.

Both are built into the platform and available through the API and SDK.

Thread-scoped memory

Thread-scoped memory stores key-value pairs within a single thread. Agents can read and write memory using built-in tools during conversations.

Tools

get_memory — retrieve a value by key:

Parameter	Type	Required	Description
`key`	string	Yes	The memory key to retrieve

Returns the stored value, or null if the key doesn't exist.

set_memory — store or delete a value:

Parameter	Type	Required	Description
`key`	string	Yes	The memory key to store
`value`	string	No	The value to store. Omit or pass empty string to delete the key

Values can be any string, including JSON.

Constraints

Thread-scoped memory is not supported for transient threads.
Memory is scoped to a specific agent and thread combination. Two agents in the same thread have separate thread memory.

Use cases

Tracking conversation state
Storing user preferences within an active conversation
Accumulating structured data across multiple turns

Long-term memory

Long-term memory stores information across conversations and helps agents recall preferences, facts, instructions, and notes over time.

Collections

Memory is organized into four system collections:

Collection	Purpose
`preferences`	User preferences, communication style, settings
`facts`	Factual information about the user or environment
`instructions`	Standing instructions and guidelines
`notes`	General observations

You can also create custom collections using the custom:{name} format, such as custom:projects.

Storing memories

await client.rest.storeAgentMemory(agent.id, {
  content: "Account tier: enterprise, region: EU-West",
  category: "facts",
  label: "account_info",
});

await client.rest.storeAgentMemory(agent.id, {
  content: "Project Alpha deadline is March 15",
  category: "custom:projects",
});

Recalling memories

const memories = await client.rest.recallAgentMemory(agent.id, {
  query: "What tier is this account?",
  max_results: 5,
  recency_days: 30,
});

for (const memory of memories) {
  console.log(`[${memory.collection}] ${memory.content}`);
}

The platform ranks relevant memory items and returns the most useful matches for the query.

Listing and managing memories

const collections = await client.rest.listAgentMemoryCollections(agent.id);

const items = await client.rest.listAgentMemory(agent.id, {
  category: "preferences",
  limit: 20,
  offset: 0,
});

await client.rest.deleteAgentMemory(agent.id, itemId);

Automatic memory capture

When enabled, ArchAstro can automatically save useful facts, preferences, instructions, and notes from completed conversations into long-term memory.

This is useful when you want agents to build continuity over time without requiring users to repeat the same information in every new conversation.

What it captures

Typical examples include:

communication preferences
project details and deadlines
standing instructions
durable facts the agent should remember later

Treat automatic memory capture as an optional product behavior that improves continuity. If your use case requires tighter retention or more explicit review, you can rely on direct memory APIs instead of automatic capture.

How memory connects to agent context

Long-term memory becomes part of the agent's broader available context alongside approved documents, messages, and other connected knowledge sources.

Agent query
    │
    ▼
Relevant context lookup
    │
    ├── Connected knowledge sources
    ├── Long-term memories
    └── Thread-scoped memory
    │
    ▼
Ranked results returned to agent

Design patterns

Remember-then-act

A user shares a durable preference such as response style.
The preference is saved to memory.
In a later conversation, the agent recalls it before responding.

Shared knowledge base

Multiple agents can read from the same approved memory collections when they share access to the same context.

Progressive profiling

Use memory to build a richer understanding over time:

first interaction: role and basic preferences
later interaction: tools, workflows, and team structure
future interaction: use that context without requiring repetition

Agent Memory