Memory System

Axiom uses a file-based, plain-Markdown memory system. Everything the agent remembers lives under /data/memory/ as readable, hand-editable files. No opaque vector blob — you can cat, grep, and git diff your agent's memory. A small SQLite-backed fact store sits next to the files for atomic facts that the agent searches on demand.

Why files?

• Inspectable. You always know what the agent thinks it knows.
• Portable. Back up the volume, you've backed up the memory.
• User-editable. Override or correct anything via the web UI's Memory page or by editing the file directly.
• Diffable. git init the directory and you have full history of how the agent's understanding evolved.

Memory tiers

The memory directory looks like this:

/data/memory/
├── SOUL.md                  ← personality
├── MEMORY.md                ← long-term curated memory
├── daily/
│   ├── 2025-01-14.md        ← per-day session notes
│   └── …
├── users/
│   ├── admin.md             ← per-user profile
│   └── …
├── wiki/
│   ├── homelab.md           ← agent-maintained knowledge base
│   └── …
└── sources/                 ← immutable raw material the wiki cites
    ├── articles/
    ├── youtube/
    ├── podcasts/
    ├── papers/
    └── notes/

Plus one non-file tier: the SQLite memories table, holding atomic facts the agent searches on demand.

Each tier has a clear role; the next sections walk through them.

SOUL - SOUL.md

SOUL.md defines who the agent is — its tone, voice, character. It's the most stable file in memory: written by the user, rarely touched by the agent, and intended to be rewritten when you want to change the agent's "vibe". The default template is conservative; customize it. (Note: concrete communication rules — "no filler", "use markdown lists" — belong in AGENTS.md, not here.)

Core memory - MEMORY.md

The agent's long-term scratchpad: learned lessons, recurring patterns, technical decisions, corrections. Included in every prompt, so keep it short and curated.

The agent edits it directly with edit_file / write_file whenever it learns something durable. The nightly consolidation job also promotes content here from daily notes.

Daily notes - daily/<date>.md

Per-day activity log. The agent appends entries during a session when something is worth noting, and the session-end job adds a short summary when the session times out. The most recent few days are loaded into every prompt as recent context.

Daily files are append-only source material for consolidation — the consolidator reads them but never edits them. Older days get folded into MEMORY.md, user profiles, or wiki pages by the nightly job, and the dailies are then trimmed.

User profiles - users/<username>.md

One file per user, holding name, location, communication preferences, work context, interests — anything person-specific. Loaded into the prompt only when that user is talking to the agent, so multi-user setups stay clean.

The agent maintains the file as it learns about the user.

Wiki - wiki/*.md

The agent's own structured knowledge base: project notes, architecture decisions, key dependencies, evergreen concepts. Pages have an optional YAML frontmatter (aliases: [Foo, foo-thing]) and are listed in the system prompt by title only — the agent loads a page on demand with read_file when the topic comes up.

The wiki is shared across all users, so sensitive personal data (health, finances, relationships) belongs in the user profile, not in a wiki page.

The agent maintains the wiki autonomously: it adds new pages, extends existing ones, merges duplicates, fixes stale entries, and keeps cross-links healthy without asking. Only genuine contradictions (new info conflicts with an existing page) get escalated to the user.

For non-trivial wiki work, the agent uses the bundled wiki skill (/data/skills_agent/wiki/SKILL.md), which carries the canonical conventions for frontmatter, filenames, cross-links, and the ## Sources section.

Sources - sources/**/*.md

The immutable, append-only layer beneath the wiki. Articles, YouTube transcripts, podcasts, papers, hand-captured notes — raw material the wiki cites so factual claims stay verifiable. Subfolders (articles/, youtube/, podcasts/, papers/, notes/) are created on first use.

Each file follows <yyyy-mm-dd>-<slug>.md with YAML frontmatter (source_type, url, author, captured) and the raw captured body. The agent archives sources during consolidation or when ingesting external material; it never rewrites an existing file — if the upstream changes, it adds a new dated entry. Wiki pages link back to sources in a ## Sources (or ## Quellen) section.

Facts - memories table

Not a file — a small SQLite-backed store of atomic, sentence-sized facts ("User prefers npm over yarn", "The project's PostgreSQL runs on port 5433").

The agent doesn't see this table in its prompt. Instead, it queries it on demand via the search_memories tool, which supports FTS5 syntax (word matching, prefix*, phrase queries, boolean operators). This lets long-term memory grow far beyond what fits in a single prompt while keeping the prompt small.

Facts are written automatically by the session-end fact-extraction job. They're per-user and timestamped, so the agent can answer "what did we decide about X?" even months later.

Multiple users

When several people share one instance, memory is split by privacy:

• Private per user: profile, daily notes (session summaries), facts, chat history and workspace. The first account keeps the paths above; every other user gets /data/users/<username>/ (PROFILE.md, HEARTBEAT.md, daily/) and /workspace/<username>/.
• Shared: MEMORY.md, the wiki, sources and skills. They hold general knowledge only. The agent keeps personal information out of them and writes it to the user's profile.

A session summary always lands in the daily folder of the session's owner and never appears in another user's prompt. read_chat_history and search_memories only return the caller's own conversations and facts.

Session end

A session is a continuous chunk of conversation. It ends when either sessionTimeoutMinutes of inactivity passes (default 30) or the user runs the /new command in the chat. On session end Axiom runs two background jobs in parallel: one writes a summary into the daily note, the other extracts atomic facts. Both have their own provider knob and tuning under Settings → Memory.

Session summary

A small LLM gets the transcript and writes a short activity-log entry, appended to memory/daily/<date>.md. This is what the nightly consolidation later reads when it promotes durable content into MEMORY.md, user profiles, and the wiki.

The summary provider defaults to the active chat provider; most setups override it with something cheap and fast under Settings → Memory → Sessions.

Fact extraction

In parallel, the transcript is fed to an extraction model that pulls out atomic, sentence-sized facts and writes them into the memories table. Sessions shorter than minSessionMessages are skipped — there's nothing worth extracting from a two-line exchange.

Facts are deduplicated against existing entries (token-overlap heuristic) and capped at 10 per session. The agent retrieves them later via search_memories.

Tune under Settings → Memory → Fact extraction.

Memory consolidation

The nightly memory consolidation job condenses the last few days of daily/<date>.md files into durable entries in MEMORY.md, user profiles, and wiki pages — then trims the dailies. This keeps long-term memory rich and the prompt small.

How aggressively it promotes vs. drops is governed by /data/config/CONSOLIDATION.md — the prompt the consolidator uses to judge each candidate entry. See Agent Instructions → CONSOLIDATION.md for the template and tuning tips.

On instances with several users, consolidation runs once per user, sequentially, with the bootstrap admin (the first account) last. A user's run reads only that user's daily notes and chat history and may update their own profile, the shared MEMORY.md (general lessons only, no personal data) and the wiki. Users with no daily notes in the lookback window are skipped. The global steps — wiki lint, source coverage and MEMORY.md compaction — run only in the admin run. A manual run (admin only) executes the whole sequence, and the consolidation status reflects the combined result. Single-user instances behave as before.

Schedule, lookback window, and provider are configured under Settings → Memory. You can also trigger a consolidation run manually from the Memory page in the web UI.

See also

• Agent Instructions — the user-editable AGENTS.md, CONSOLIDATION.md, and HEARTBEAT.md config files. They shape behavior, not memory.
• System Prompt — how the memory tiers above are composed into the live prompt the model sees on every turn.
• Settings → Memory — session timeout, fact extraction, and consolidation schedule.
• Built-in Tools → search_memories — the tool the agent uses to query the fact store.