Memory
Two-layer memory — always-on file-based memory plus an opt-in retrieval pipeline for session-spanning recall.
Long-running coding work needs memory that survives across sessions. Syntax's memory system has two layers, designed so the always-on layer is simple and predictable while the optional second layer adds sophisticated retrieval when you want it.
Layer 1 — always on
A canonical memory file in your project (and a per-user one) is loaded into every agent context automatically. Layer 1 memory is:
- File-based. It's a normal Markdown file you can read, edit, and diff like any other file.
- Opt-in by content. You write what you want remembered; the agent doesn't auto-write here.
- Always loaded. Every agent turn sees it, so guidance you write there is enforced consistently.
This is the right layer for "always-true" facts about your project, your preferences, or your conventions — things you want every agent turn to know without having to repeat.
Layer 2 — opt-in retrieval
Layer 2 is a richer system that lets the agent record discrete memory entries and retrieve them on demand:
- Hybrid retrieval. Combines lexical and semantic search over a per-user memory store.
- Per-turn auto-retrieval. When enabled, every agent turn automatically pulls in memories relevant to the current input before producing a response.
memory_searchtool. The agent can also explicitly search memory mid-turn.- Schema-stable storage. The on-disk shape is durable, so memory built up over many sessions stays intact across upgrades.
Layer 2 is the right layer for "things the agent learned" — facts about your codebase, decisions made in earlier sessions, lessons learned from failed approaches.
When to use which
- Layer 1 for: explicit guidance, conventions, "always-do" / "never-do" rules, project context that doesn't change much.
- Layer 2 for: incidental learnings, debugging notes, history of decisions, anything you'd otherwise forget.
You can use both at once. Most teams start with Layer 1 alone and adopt Layer 2 once they have multi-session workflows where recall becomes valuable.
Where memory lives
Memory storage lives in your home directory under predictable paths that you can inspect and back up. Layer 1 is plain Markdown; Layer 2 is a small structured store you don't have to read by hand.
Memory and Agent Handoff
When a session crosses the long-context threshold and Syntax does an Agent Handoff, the memory system is unaffected. Layer 1 is loaded fresh for the new agent; Layer 2's retrieval works the same way. Memory is the right answer to "this information should survive across handoffs and across sessions"; handoff is the right answer to "this conversation should keep going indefinitely".