Skip to main content
NO BLACK BOX

​
Memory you can open in a text editor.

Every fact an Actionist agent learns lives in a plain Markdown file on your machine — readable, editable, version-controllable. No black-box vector store. No context that silently disappears when the session ends.

The model

​
Memory lives in three places.

Every surface is the same underlying files — you interact with them wherever is most natural. Below: one fact, seen from all three sides.

Memory instructions”Log every client call outcome. Prefer bullet points.”auto-saves
CRM bucketCustomer accounts and historyRead / Write

The primary configuration surface, inside the Agent Studio: Agents → select an agent → Memory tab (Brain icon). Instructions, bucket access, and the knowledge corpus — without leaving the app.

company/crm/accounts/northwind.md
## Northwind Trading
- Tier: enterprise · renewal: October
- Reports as slides, never PDF (CEO reads on phone)

Plain Markdown on disk. Open company/Memory.md or agents/{id}/memory/Memory.md in any editor to read, edit, or version-control what your agents know.

chat · maya
youHow does Northwind want their reports?
tool · Search Memory · “northwind report format”
mayaSlides, never PDF — their CEO reads on a phone. Saved from your call on June 9.

Agents call Search Memory (memory_search) and Read Memory (memory_get) automatically — in conversation, in workflows, and on scheduled runs.

The write loop

​
Watch an agent remember.

A background curator watches every conversation, workflow, and scheduled run, and decides what is worth keeping. Below: one agent’s day, landing in her journal as it happens.

agents/maya/memory/TODAY.md
chat · maya · 09:14
09:14Client call with Northwind — they want the Q3 report in slide form, not PDF.
09:14Preference saved: reports as slides for Northwind going forward.
workflow · invoice-chase · 11:02
11:02Sent 3 payment reminders. Invoice #2041 escalated to second notice.
chat · maya · 14:38
14:38New rule from the team: always CC legal@ on contract emails.
14:39Promoted to Memory.md — this one is permanent.
schedule · daily-digest · 17:00
17:00Digest sent. Open rate trending up since switching to bullet summaries.
Nothing blocks the agent. Curation runs asynchronously in the background — the conversation never waits for a memory write.
Today, then history. The journal rolls into dated history files; durable rules get promoted to Memory.md and survive forever.
Everything is a file. Open the workspace in any editor and read exactly what your agent knows. Edit it. Version it.
Under the hood

​
Five stops from words to memory.

ConversationChats, workflows, and scheduled runs emit events as they happen.
Event queueObservations accumulate quietly, off the hot path.
Write plannerA background model reads the batch and plans precise file edits.
Markdown filesPlans become atomic writes to the agent’s memory tree.
INDEX.mdEvery durable write gets a one-line entry in a human-readable index.
Context, spent deliberately

​
What the agent reads before you type a word.

Every session opens with a deterministic preload: up to six files across five sources, wrapped in named sections, inside a total budget of 8,000 tokens — no search, no guessing. Hover a segment to inspect it.

registry
user
Memory.md
TODAY.md
history ×2
company context · 4,000 charsuser profile · 4,000 charsagent memory · 8,000 charstoday’s journal · 8,000 charsrecent history · 4,000 × 2
Truncation is front-first — when a file exceeds its budget, the oldest content is dropped and the newest is kept. If you let Memory.md or TODAY.md grow uncurated, early important context disappears silently. Keep both files tight.
The studio

​
The Memory tab, panel by panel.

Reach it from Agents → select an agent → Memory tab (Brain icon). Three panels, each controlling a different layer.

Agent Studio — Maya · Memory
OverviewToolsMemoryChannelsSchedule
Memory instructions
Log every client call outcome.
Prefer bullet points.
Never store API tokens.
auto-saves
Memory buckets
Global memoryRead/Write
CRMR/W
ProductsRead
PoliciesNo access
OperationsNo access
DocsRead
Knowledge corpus
Upload File.md .txt .pdf .docx up to 10 MB
pricing-2026.pdfextracted

Memory instructions

The markdown editor at the top of the tab writes directly to agents/{id}/memory/Memory.md. Use it to tell the agent what is worth remembering and how: “Log every client call outcome. Prefer bullet points. Never store API tokens.”Changes auto-save as you type. To revert to the default, click the Reset button (arrow-clockwise icon) in the panel header.
Keep instructions under roughly 200 words. Memory.md is injected verbatim into every session within the 8k-token preload budget. A long essay eats into the budget for TODAY.md and recent history — write directives, not prose.
Buckets are named scopes. Each one maps to a file or folder of Markdown on disk. The tab shows a row per bucket with a three-way permission control: No access (invisible to the agent), Read (search and recall), Read/Write (search, recall, and save new facts).The Global memory bucket (Globe icon, always at the top) covers workspace-wide scratch memory shared by every agent. It is always included in search regardless of its permission setting.The six built-in company buckets cover shared ground truth:
BucketScopeContents
Business Infocompany:business-infoMission, values, company facts
Productscompany:productsProduct catalogue and specs
Policiescompany:policiesInternal rules and procedures
Operationscompany:operationsProcesses and runbooks
CRMcompany:crmCustomer accounts and history
Docscompany:docsReference documentation
You can also let one agent read another agent’s memory directory by adding agent:{targetId} as a scope — useful for coordinator agents that need to read a specialist’s learned facts.
The Knowledge Corpus is a private document library for this specific agent. Upload reference files — specs, pricing tables, runbooks, FAQs — and the agent retrieves the relevant excerpt via semantic search rather than loading the whole document on every turn.“Private documents this agent can reference. Chunks are embedded and retrieved; nothing leaves your workspace.”Click Upload File to add a document. Accepted types for indexing: .md, .txt, .csv, .json, .yaml, .yml, .toml, .ini, .log. Rich document formats (.pdf, .docx, .xlsx) go through a text-extraction step before indexing. Maximum file size: 10 MB per file.To remove a file, hover the row and click the Trash icon. Confirm in the dialog: “Delete [filename] from the knowledge corpus?”
Try it · permissions

​
Permissions you can feel.

Memory is bucketed by scope so an agent only sees what it needs — a data diet, not a free-for-all. The matrix below starts in the recommended setup for a CRM agent. Change anything; watch the agent’s world change.

Set each bucket’s access
Business InfoMission, values, company facts
ProductsProduct catalogue and specs
PoliciesInternal rules and procedures
OperationsProcesses and runbooks
CRMCustomer accounts and history
DocsReference documentation
What this agent sees
agents/maya/memory/ — always
company/Memory.md — always
company/business/ — no access— read only— read + write
company/products/ — no access— read only— read + write
company/policies/ — no access— read only— read + write
company/operations/ — no access— read only— read + write
company/crm/ — no access— read only— read + write
company/docs/ — no access— read only— read + write
Struck-through paths are invisible to the agent — in chat, in workflows, and in search.

​
Why the CRM preset looks like this

CRM gets Read/Write

The CRM agent owns customer data. Read/Write lets it both recall existing records and save new ones — call outcomes, updated deal stages, contact notes.

Products gets Read

The agent references your catalogue when qualifying leads, but it shouldn’t rewrite product facts. Read-only keeps the source of truth safe.

Operations and Policies get No access

A CRM agent has no reason to read internal process docs or policy files. No access keeps the context clean and prevents accidental contamination.

Verify with a test message

Open a chat and ask: “What do you know about our pricing?” Watch the Search Memory tool call and confirm it returns results from the CRM and Products buckets only.
Always give at least one bucket Read/Write for any agent that runs on a schedule or trigger. If every bucket is Read or No access, the memory agent plans writes it cannot execute — the agent appears to work normally but retains nothing between sessions.
Adding a custom bucket. Edit company/Memory.md directly using the heading-based format below. After saving, the new bucket appears in all agents’ Memory tabs immediately.
### My Bucket Name
- Scope: `company:my-bucket`
- Type: file
- Path: `company/my-bucket.md`
- Description: What this bucket stores
Knowledge corpus

​
Turn documents into searchable knowledge.

Upload a 50-page product spec once. The agent retrieves a targeted excerpt on every relevant turn — instead of re-reading the whole file or asking you to paste it in chat. Watch a file move through its lifecycle:

pricing-2026.pdf · 2.4 MBUploading…Extracting text…Uploaded — indexing pending. Searchable shortly.extracted indexed and searchable

Open the Knowledge corpus panel

In the Memory tab, scroll to the Knowledge corpus panel and click Upload File.

Pick a file

Text types index directly: .md, .txt, .csv, .json, .yaml, .yml, .toml, .ini, .log. Rich documents (.pdf, .docx, .xlsx) are text-extracted first. Maximum size: 10 MB per file.

Watch the lifecycle

Exactly the animation above: Uploading… → Extracting text… (rich files) → indexing pending → the extracted badge. If you instead see “No text could be extracted from this document”, the file is image-only — nothing is searchable.

Verify the agent can find it

Ask the agent a question the document should answer. It calls Search Memory and returns a ranked excerpt — confirm the snippet is from your file.

Remove a file

Hover the file row and click the Trash icon. Confirm: “Delete [filename] from the knowledge corpus?” The file and its index entries are removed immediately.
Wait for the extracted badge before relying on a PDF or DOCX in a live agent. “Indexing pending” means not yet searchable; “No text could be extracted” means it never will be.
Try it · recall

​
Recall, ranked.

Two tools power recall, and agents call them automatically — you see the tool calls inline in chat and in workflow traces. Pick a query and watch the ranking.

memory_search(“report format”)
memory_search(“contract emails”)
memory_search(“demo follow-up”)
memory_search(“tone of voice”)
agents/maya/memory/Memory.md:120.91
Reports for Northwind go out as slides, never PDF — their CEO reads on a phone.
company/docs/brand-voice.extracted.md:190.48
Tone of voice: direct, warm, zero filler. Short sentences win. No exclamation marks.
company/crm/accounts/northwind.md:20.37
Northwind Trading — enterprise tier, renewal in October, champion: Dana Voss.
company/policies/email.md:40.94
Always CC legal@ on anything containing contract terms or pricing commitments.
agents/maya/memory/TODAY.md:140.52
New rule from the team: always CC legal@ on contract emails. Promoted to Memory.md.
company/products/pricing.md:70.29
Pro plan pools usage across the team; Basic is single-seat with a monthly reset.
agents/maya/memory/history/2026-06-09.md:310.89
Demo follow-ups convert best when sent within 4 hours, with one concrete next step.
company/crm/accounts/northwind.md:20.44
Northwind Trading — enterprise tier, renewal in October, champion: Dana Voss.
agents/maya/memory/TODAY.md:80.33
Invoice #2041 escalated to second notice; finance wants weekly status on it.
company/docs/brand-voice.extracted.md:190.93
Tone of voice: direct, warm, zero filler. Short sentences win. No exclamation marks.
agents/maya/memory/Memory.md:120.41
Reports for Northwind go out as slides, never PDF — their CEO reads on a phone.
company/policies/email.md:40.27
Always CC legal@ on anything containing contract terms or pricing commitments.
Ranked with the real engine’s hybrid weights: 0.6 semantic similarity · 0.25 keyword match · 0.15 recency, re-ranked so one document never dominates. Demo data, real scoring shape.

”You explained the Northwind report format once. In March.”

maya · memory_search
ToolDisplay nameWhat it doesKey default
memory_searchSearch MemorySemantic + keyword hybrid search across all permitted buckets and corpus files. Returns ranked results with file path, line range, score, and snippet.Up to 6 results per call
memory_getRead MemoryReads a specific memory file. Accepts path (required), from (start line, optional), and lines (line count, optional). Scope-enforced.Up to 200 lines per call; omit lines to read the full file (also capped at 200)
memory_get is scope-enforced. An agent can only read files in buckets where it has at least Read permission — attempting to read outside the permitted scope returns an error, not the file contents. Recall works the same everywhere: in chat, in workflows, and on scheduled runs, with each tool call visible in the trace.
Memory in practice

​
Three teams, one pattern.

Memory is most useful when it surfaces exactly the right context without being asked. These recipes show how agents across roles use recall and write to stay useful across sessions.

Dario · Sales
Before a call, memory_search(“northwind deal stage”) surfaces the last three touchpoints, open commitments, and the champion’s name — all logged automatically from prior sessions. Dario opens the call with context instead of asking the CRM for a briefing.
saves ~6 min per call
Priya · Support lead
A support ticket asks about refund eligibility. The agent runs memory_search(“refund policy”) against the Policies bucket, finds the exact clause, and cites the source file and line number in its reply — no tab-switching, no guesswork.
cited answer in ~8 sec
Maya · Marketing Manager
Maya said once: “Northwind reports go out as slides, never PDF.” That preference was written to Memory.md and now applies on every run — campaign drafts, digest emails, and scheduled summaries all arrive in the right format without reminders.
zero repeat instructions
Best practices

​
Memory habits that pay off.

Six habits that prevent the most common memory failures — and make the most of the context you have.

Memory instructions are injected verbatim at session start, inside the 8,000-token preload budget. Every word you write competes with TODAY.md and recent history. Write short, imperative sentences: “Log every client call outcome. Prefer bullet points. Never store API tokens.” Past 200 words, you are writing prose that belongs in a corpus document.
Think of each agent as owning the buckets it controls: your CRM agent gets Read/Write on CRM, Read on Products, No access on Policies. Giving multiple agents Read/Write on the same bucket creates contention — agent A’s writes can contradict agent B’s in the same file. One writer per bucket is the clean pattern.
If every bucket is Read or No access, the memory subsystem plans writes it cannot execute. The agent appears to work — answers questions, runs workflows — but retains nothing, and the next session starts from zero. For any scheduled or triggered agent, confirm one Read/Write bucket before production.
Pasting a 50-page spec into chat loads the whole document into context every turn. Uploading it to the corpus chunks and indexes it — the agent retrieves the relevant excerpt only when needed. Good corpus candidates: specs, pricing tables, SLAs, runbooks, brand guidelines, FAQs. Bad candidates: short facts (Memory.md) and image-only PDFs (nothing extracts).
Rich documents (PDF, DOCX, XLSX) are text-extracted before indexing. The extracted badge confirms usable text came out. “No text could be extracted” means the file is image-only — OCR is not performed, nothing is searchable. Don’t put a corpus file in a production agent’s remit until the badge appears.
The curator maintains agents/{id}/memory/INDEX.md automatically — one line per memory file, hard-capped at 200 lines or 25 KB, oldest entries dropped first. For agents running for months, open it occasionally and confirm your most important facts still have entries. If a critical early fact was evicted, re-surface it: ask the agent to log it again, or edit the file directly.
Why it’s built this way

​
Four principles, no compromises.

Plain Markdown

Human-readable files, not embeddings in a vault. What you can read, you can trust.

Permissioned

Bucket-level read/write grants per agent. A support agent never wanders into finance.

On-device

The store and its search index live on your machine, not in someone else’s cloud.

Survives sessions

Monday’s lesson still applies on Friday. Memory is the product, not a side effect.
Always on

​
Memory that works while you sleep.

Configure buckets once. Upload your reference docs. Let the agent carry context forward on every session, every schedule, every run.

Open the DashboardEmail the team

Every fact lives in a plain file you own — readable, editable, version-controllable.
Permissioned by bucket · Indexed on-device · Nothing leaves your workspace.

Keep going

​
Next steps.

Agents

Configure the agent that holds this memory — tools, approval mode, channels, and schedule.

Files

Browse and edit the underlying Markdown files your agents read and write.

Schedules

Put a memory-backed agent on a recurring schedule — and why bucket permissions matter for unattended runs.

Skills

Portable behavior packs that pair well with memory — a skill plus a well-scoped bucket makes a focused specialist.