Memory

Agentix has two distinct memory systems that serve different purposes:

System	What it is	Scope
Context memory	Conversation history kept in the context window	Current session only
Memories tool	Persistent notes the agent reads and writes across sessions	Survives session restarts

---

Context memory

The agent automatically manages how much conversation history it keeps in the context window.

options = AgentixAgentOptions(
    conversation_summarization_enabled=True,   # default: True — summarize old messages
    max_conversation_window=10,                # default: 10 — keep last N messages verbatim
    max_context_tokens=16384,                  # default: 16384 — summarize when exceeded
)

When the conversation exceeds max_context_tokens, Agentix summarizes the oldest messages so the agent retains the gist without filling the window. The PreCompact hook fires before each compaction:

from agentix import HookMatcher

async def on_compact(hook_input: dict, context) -> None:
    print(f"Compacting — {hook_input['current_count']} messages in history")

options = AgentixAgentOptions(
    hooks={"PreCompact": [HookMatcher(matcher=None, hooks=[on_compact])]}
)

Disable summarization (older messages are dropped instead — not recommended for long sessions):

options = AgentixAgentOptions(conversation_summarization_enabled=False)

---

Memories tool

The Memories built-in tool lets the agent persist facts and notes to disk. Unlike conversation history, memories survive across sessions — the agent can record something in one run and recall it in a completely different session later.

Enabling memories

memories_enabled defaults to False. You must explicitly enable it:

options = AgentixAgentOptions(
    memories_enabled=True,
)

When enabled, the Memories tool is registered and the agent's system prompt is updated with instructions on how to use it.

Interaction with allowed_tools:

• If allowed_tools is empty (the default — all tools allowed), the Memories tool is registered and usable without any further configuration.
• If allowed_tools is non-empty (a restricted allow-list), Memories is automatically appended to it — unless it is explicitly listed in disallowed_tools.

# Memories auto-appended to the restricted allow-list
options = AgentixAgentOptions(
    memories_enabled=True,
    allowed_tools=["Read", "Glob", "Grep"],
    # effective allow-list becomes ["Read", "Glob", "Grep", "Memories"]
)

# Prevent Memories even when memories_enabled=True
options = AgentixAgentOptions(
    memories_enabled=True,
    disallowed_tools=["Memories"],
)

How the agent uses it

The agent reads and writes memory files autonomously based on context. Guide this with your system prompt:

options = AgentixAgentOptions(
    memories_enabled=True,
    system_prompt="""You are a personal assistant.
Use the Memories tool to remember user preferences, names, and facts they tell you.
Always read your memories at the start of each conversation.""",
)

Storage location

Memories for the main agent are stored at:

<cwd>/.agentix/memories/

Where cwd is the working directory set on AgentixAgentOptions (defaults to the process working directory). The Memories tool supports view, create, str_replace, delete, and rename operations on files within this directory.

Sub-agents do not inherit memories_enabled. They use the memory field on AgentDefinition instead — see below.

---

Sub-agent memory scoping

Each sub-agent in a multi-agent setup has its own memory scope that controls where (and whether) it stores memories:

from agentix import AgentDefinition, AgentixAgentOptions

options = AgentixAgentOptions(
    agents={
        "researcher": AgentDefinition(
            name="researcher",
            description="Gathers information on a topic.",
            tools=["WebSearch", "WebFetch"],
            memory="project",   # store memories in .agentix/agent-memory/researcher/
        ),
        "writer": AgentDefinition(
            name="writer",
            description="Writes polished content from research notes.",
            tools=["Read", "Write"],
            memory="none",      # default — no persistent memory
        ),
    }
)

Memory scope values

Value	Storage path	Visibility
"none"	—	No persistent memory (default)
"user"	~/.agentix/agent-memory/<name>/	Shared across all projects on this machine
"project"	<cwd>/.agentix/agent-memory/<name>/	Per-project; can be committed to source control
"local"	<cwd>/.agentix/agent-memory-local/<name>/	Per-project, machine-local; gitignore this

Where <name> is the sanitized sub-agent name.

Guidance:

• Use "project" when sub-agents accumulate domain knowledge that should persist for the whole team.
• Use "user" when sub-agents learn per-developer preferences across projects.
• Use "local" for sensitive or machine-specific facts that shouldn't be committed.
• Leave as "none" (the default) when a sub-agent is stateless and repeatable.

---

Relationship to sessions

Memory and sessions are independent:

• Sessions track the conversation between you and the agent (turn-by-turn messages).
• Memories track facts the agent chooses to persist (agent-authored notes in files).

Clearing a session with client.reset_session() does not erase memories. The agent's stored notes persist until you delete the files from disk.

See Sessions for managing conversation history, and Storage Backends for plugging in distributed storage.