Memory

Sophon's memory system is what keeps the agent coherent across conversations. It stores facts, preferences, and daily activity; builds an entity graph of the people, projects, and places it knows about; and injects relevant context into every LLM call. The agent can write, read, search, forget, and explore memory as a graph during any chat.

What gets remembered

There are two persistent memory surfaces:

Long-term memory — individual entries the agent (or you) chose to keep. Each entry has content, a category (fact, preference, or observation), a scope (user or agent), and is linked into an entity graph. Examples:

• fact — "Project Atlas ships on March 15"
• preference — "User prefers dark mode"
• observation — "User opens GitHub first thing most mornings"

Short-term memory (daily logs) — timestamped summary of what happened each day. One row per interaction; the agent reads the last two days on every turn.

[2026-04-22 10:30] Discussed Atlas deadline — confirmed Mar 15
[2026-04-22 14:15] Uploaded Q1-competitors.pdf; summarized to team
[2026-04-22 16:00] Sent email summary (approved)

Daily logs capture context; long-term entries capture the durable conclusions you want to survive beyond the window.

Scopes — user vs agent

Every long-term entry has a scope:

When the context assembler builds the system prompt, it fetches both: all user-scoped entries + the active agent's agent-scoped entries. So if you tell the writer agent to use formal tone, the research agent is unaffected.

The entity graph

Every memory entry is automatically linked to entities (people, projects, places, dates) that appear in the content. This turns your memories into a graph you can explore.

Two extraction paths:

• LLM link extraction — when you write a memory, a fast-tier LLM scans it for named entities and wires them in.
• Wikilinks — you can write links explicitly with [[Entity Name]] syntax and Sophon will parse them:

User is planning a trip to [[Tirana]] with [[Ermal]] for the [[Atlas launch]]

That memory links to three entities — Tirana, Ermal, Atlas launch — and any future query that mentions any of those surfaces this entry too. Wikilinks also support an alias form, [[Target|Display]]: the part before the | is the canonical entity that gets linked, the part after is display text only. So [[Sarah Chen|Sarah]] reads as "Sarah" in the entry but links the entity Sarah Chen — the display text is presentation-only and is never recorded as an alias on the entity.

The Dashboard Memory page renders the graph so you can see what knows what. For the full graph story — the explorer, Mermaid export, duplicate detection and merge — see Memory Graph.

The six memory tools

The agent has six tools for working with memory:

memory.write

Saves a new entry. The agent calls this when it learns something worth keeping, or when you say "remember that…".

Risk: Medium — triggers auto-extraction of entities and a write. Not gated unless part of a plan.

memory.search

Semantic + keyword hybrid search. Returns the top matches with relevance scores.

Risk: None — read-only.

memory.list

Paginated listing of entries (no search). Useful for "show me everything you remember about me."

Risk: None.

memory.forget

Deletes an entry by ID. Irreversible — requires user approval.

Risk: Medium — triggers approval gate. "Forget everything" is a separate, Critical-risk flow handled in the Dashboard, not via this tool.

memory.graph

Unified graph inspector — one tool, four operations over the entity graph.

Risk: None — read-only.

memory.diagram

Renders the graph (or a cluster around a seed) as a Mermaid flowchart. Chat renders the fenced diagram inline, theme-aware — use it when you ask the agent to "show" or "draw" the graph.

Risk: None — read-only.

Temporal facts

Facts change. Instead of deleting the old entry and writing a fresh one, pass supersedes to memory.write (or POST /api/memory/entries):

{
  "content": "Project Atlas now ships on April 2",
  "category": "fact",
  "supersedes": "mem_abc123"
}

The new entry replaces the old one. Superseded entries drop out of default views and search (their vector is deleted), but they are never destroyed — pass includeSuperseded=true to inspect them. The Dashboard shows a per-entry history, so you can see how a fact evolved over time.

Consolidation and retention

Daily logs aren't meant to pile up forever. MemoryConsolidationJob — a Quartz cron job, daily at 03:00 UTC by default — reviews recent daily logs and promotes the durable facts into long-term memory entries through the same write pipeline memory.write uses. Immediately after each sweep, it applies retention cleanup: daily logs older than RetentionDays (default 30) are removed.

Context assembly — what the LLM actually sees

On every turn, the context assembler builds the system prompt:

You are Sophon, an intelligent AI personal assistant.

## Shared Memory (user scope)
- User lives in Tirana, Albania
- Project "Atlas" deadline is March 15
- Prefers TypeScript over JavaScript

## Agent Memory (this agent)
- Ada uses concise responses, no emoji
- Greet user as "Enes"

## Recent Activity (last 2 days)
[2026-04-21 09:15] Reviewed PR #423, merged
[2026-04-22 10:30] Discussed Atlas deadline
[2026-04-22 14:15] Uploaded competitors.pdf, summarized

Budgets:

• Up to 50 user-scoped entries
• Up to 50 agent-scoped entries
• Last 2 days of daily logs
• Last 100 chat messages

These caps keep the prompt from ballooning. If memory grows past them, the most relevant entries float to the top — long-term entries are scored against the current message and ranked.

Dashboard — the Memory module

The Dashboard has a Memory page at /memory with four tabs:

• Entries — paginated list of long-term entries. Filter by scope, category, agent. Add, edit, or delete.
• Logs — daily activity log. Filter by agent and date range.
• Search — hybrid search UI. Results show relevance scores.
• Graph — the graph explorer v2 at /memory/graph: force-directed layout, kind-chip filters, date window, node-cap presets, a co-mention overlay, and Mermaid export. A Duplicates review sheet surfaces likely duplicate entities for merge or dismiss. Full tour: Memory Graph.

Every entry has an ID you can reference in memory.forget or memory.graph.

CLI

sophon memory search "project deadline"
sophon memory list --scope user --limit 20
sophon memory list --agent writer
sophon memory forget mem_abc123   # prompts for confirmation

Storage by tier

Schema:

• MemoryEntries — long-term, indexed on (UserId, AgentId) + tenant
• DailyLogEntries — short-term, indexed on (UserId, AgentId, CreatedAt) + tenant
• MemoryEntities / MemoryLinks — the graph, indexed on entity name

SQLite DateTimeOffset doesn't sort in queries, so the engine sorts client-side after fetch. Postgres sorts natively.

Legacy MEMORY.md migration

If you're upgrading from pre-database versions that stored memory in ~/.sophon/memory/MEMORY.md and daily log files, Sophon migrates on first startup:

1. Reads MEMORY.md, treats each - bullet as a user-scoped long-term entry.
2. Reads memory/daily/*.md files, imports as daily log rows.
3. Skips migration if the DB already has entries (idempotent).

No manual step is required.

Security and isolation

• User isolation — every query filters by authenticated user ID. Cross-user reads are impossible.
• Agent isolation — agent-scoped entries are visible only to the owning agent.
• Tenant isolation (Enterprise) — EF Core global query filters enforce tenant boundaries on every query.
• No secrets in memory — the credential vault and memory are separate stores. API keys, OAuth tokens, and other secrets never land in memory and never leak into LLM prompts.
• Approval for forgets — memory.forget and any "forget all" operation trigger the approval gate.
• Vector metadata filtering — semantic search filters results server-side by user + agent before returning, so a malformed query can't return someone else's memories.

Where to go next

• Agents & SOUL — scope and routing rules
• Approval Gates — why memory.forget gates
• Connections — services that populate memory automatically