Memory in AgenticX

Memory is how an agent keeps identity, recent work, and a bounded window. Near's main path is workspace files (MEMORY.md, memory/*.md) plus session messages.json, then recall injected into the Meta system prompt. Optional Mem0 / other stores are library backends, not the Desktop default.

Worked example: write a preference, see it next turn

Scene. You want Meta to keep calling you a nickname and avoid a formatting habit.

1. Put the fact in ~/.agenticx/workspace/MEMORY.md or memory/*.md (or the user-preference field in Settings — that is injected via _build_user_profile_block()).
2. Start a new turn in the same Meta session. The system prompt should include the recall block from _build_memory_recall_context.
3. Long threads may compact: older history becomes a summary system message. The file-backed facts should still be there even if the transcript was compacted.

What you should see. Workspace panel highlighting MEMORY.md. The next answer uses the nickname without you repeating it. Session title stays the persisted Chinese title, not a raw session_id.

Together these mechanisms approximate a layered memory stack: what must always be true (identity), what happened recently (episodes), what generalizes (semantics), what the model sees this turn (working set), what survives across sessions (long-term files and stores), and what is scoped to the user's workspace on disk.

Memory hierarchy (six-layer model)

The table maps a classic cognitive-style hierarchy to concrete AgenticX surfaces. Layers are conceptual; several features overlap in implementation.

MemoryHook

MemoryHook is an AgentHook registered on AgentRuntime with priority=-10, so it runs after hooks with higher numeric priority when run_on_agent_end walks the registry.

When it runs

• on_agent_end is invoked after a turn completes.
• It reads session.chat_history. If len(chat_history) < MIN_CHAT_TURNS * 2 it returns immediately. Defaults: MIN_CHAT_TURNS = 3 → at least six chat records required.
• Workspace directory: session.workspace_dir, else AGX_WORKSPACE_ROOT, else the user home directory.

Extraction and limits

• Heuristic only (no extra LLM call): scans the last 20 messages for Chinese user-request cues and assistant completion cues, emits bullet lines such as - 用户请求: / - 完成事项:.
• Caps output at MAX_FACTS_PER_SESSION (8) facts.

Persistence

• Appends a dated block to memory/<today>.md under the workspace. Skips append if existing daily file plus new block would exceed 8000 characters.
• If MEMORY.md exists and is under 4000 characters, appends an ## Auto-extracted section with up to four of the facts.

Scratchpad

• Merges facts into session.scratchpad["session_facts"] (concatenated with newlines).

_maybe_compact_daily

• If today's memory/<YYYY-MM-DD>.md exceeds 2000 characters, rewrites it: keeps headings, drops duplicate bullet lines keyed by the first 80 characters (case-folded), preserving first occurrence. This is deterministic deduplication, not an LLM summarizer.

1# Reference constants (agenticx/runtime/hooks/memory_hook.py)
2MIN_CHAT_TURNS = 3          # requires len(chat_history) >= MIN_CHAT_TURNS * 2
3MAX_FACTS_PER_SESSION = 8

Workspace memory

Directory layout (~/.agenticx/workspace/)

Additional session artifacts (avatars, groups) may live alongside; the search index explicitly pulls the four root markdown files plus memory/*.md.

Automatic recall: _build_memory_recall_context

Defined in agenticx/runtime/prompts/meta_agent.py. When building the Meta-Agent system prompt it:

1. Collects text from the last five user messages (up to 200 characters each).
2. Builds a query string (max 500 characters).
3. Calls WorkspaceMemoryStore.search_sync(..., limit=5, mode="hybrid").
4. Injects a ## 相关历史记忆（自动召回） section with snippets capped around 500 characters total.

If there are no user messages or no hits, the section is omitted.

Mem0 integration

Mem0 is optional. Install with the extra that pulls memory dependencies:

1pip install "agenticx[memory]"

At runtime, agenticx.memory exposes Mem0 / async variants when dependencies are present; the vendored integration under agenticx/integrations/mem0/ supports multiple vector stores and configs. Use Mem0 when you want managed long-term semantic memory (add/search APIs, hosted or local) instead of or alongside file-based MEMORY.md.

Session scratchpad

Each StudioSession carries a scratchpad dictionary persisted via SQLite (agenticx/memory/session_store.py). Besides user/agent keys from scratchpad_write, the runtime uses reserved patterns:

Meta-Agent context building reads subagent_result::* entries for "historical subagent results" when registry rows are missing.

Context compaction (ContextCompactor)

Before each turn, AgentRuntime runs ContextCompactor.maybe_compact on sanitized agent_messages.

Process:

1. Split into prefix (to compact) and suffix (retained).
2. Call the runtime LLM with a Chinese compaction instruction (temperature 0, max_tokens 400).
3. Replace the prefix with a single system message prefixed with [compacted] and the summary.
4. On failure, fall back to concatenated short snippets.

Minimum enforced floors: threshold_messages >= 8, threshold_chars >= 4000, retain_recent_messages >= 4.

Memory-related configuration

1# ~/.agenticx/config.yaml (illustrative memory block)
2memory:
3  backend: sqlite
4  path: ~/.agenticx/workspace

See also

• Configuration — global config.yaml and environment variables
• Architecture — high-level runtime overview