Memory

Memory

Long-term memory as Markdown files, with optional semantic search and automatic recall through Milvus.

malac remembers durable facts across sessions: your preferences, project conventions, decisions and why they were made, pointers to external resources. Each memory is a small Markdown file you can read, edit or delete. Optionally, a Milvus collection indexes them for semantic search and automatic recall.

How the agent uses memory

The agent has three memory tools. None of them asks for permission.

Tool	What it does
memory_save	Save one fact under a short name, with a one-line description and a scope, and for project memories a kind. Saving an existing name replaces it.
memory_search	Search memories by meaning, or by keywords when no vector store is configured
memory_forget	Delete a memory that turned out to be wrong or obsolete

An index of every memory (scope, name, description and path) is part of every system prompt, so the agent knows what it has saved and reads a memory's file when its description looks relevant. It is told to save corrections and decisions, and not to save what the code or git history already records.

You can also just ask: "remember that we deploy on Fridays only", "forget what you saved about the old API".

Scopes and files

Scope	Directory	Follows
global	~/.malac/memory/	you, in every project
project	<project>/.malac/memory/	this repository, and everyone who clones it

The project root is the nearest directory with .git. Each memory is <name>.md with frontmatter. Global memories are indexed in a generated ~/.malac/memory/MEMORY.md; project memories have a kind (command, convention, gotcha, decision or note) and are listed by kind in .malac/MALAC.md, the project's knowledge file. Commit .malac/memory/ and .malac/MALAC.md, and what malac learned reaches your other machines and your teammates. A project memory looks like this:

---
name: release-day
description: Releases go out on Fridays after the 14:00 standup
kind: convention
updated: 2026-10-25T12:00:00+00:00
---

We only tag releases on Fridays, after the 14:00 standup, so support is around on Monday.

The files are the source of truth. Edit them by hand if you like; delete one to forget it.

Commands

malac memory                    # list memories (default)
malac memory search deploy day  # search them
malac memory reindex            # rebuild the vector collection from the files

In a session, /memory lists saved memories. The web UI has a memory view with search, reindexing and deletion.

Semantic search with Milvus

Without a vector store, memory_search matches keywords in names, descriptions and bodies. With one, it searches by meaning, and auto recall attaches the closest matches to each prompt, so the agent sees relevant memories without having to look for them.

Configure a Milvus collection and an embedding model:

[memory.vector]
url = "http://localhost:19530"        # or https://<cluster>.zillizcloud.com
token_env = "MILVUS_TOKEN"            # "user:password" or an API key
collection = "malac_memory"

[memory.embeddings]
provider = "openai"                   # an OpenAI-compatible provider with /embeddings
model = "text-embedding-3-small"

How it works:

• Saving a memory embeds it (name, description and body) and upserts it into the collection. Forgetting deletes it there too.
• malac talks to Milvus over its REST API (v2), so self-hosted Milvus and Zilliz Cloud both work. It creates the collection on first use, sized to the embedding model, with a cosine index.
• Searches return the matching files' current text, so the index can never serve stale content.
• Project memories are tagged with the project root, and a search only sees global memories and the current project's.
• With auto_recall, every prompt of at least 8 characters is embedded, and up to recall_limit matches with a similarity of at least 0.4 are attached to it.

Note

The collection's vector size is fixed when it is created. If you switch to an embedding model with a different size, set a new collection name and run malac memory reindex.

The guide Vector memory with Milvus covers local Docker and Zilliz Cloud setups, and the tutorial Long-term memory with Milvus walks through saving and recalling.

Settings

Memory settings go in your user configuration; a project's .malac/config.toml cannot set them.

Key	Type	Default	Meaning
memory.enabled	bool	true	Memory tools and the index in the system prompt
memory.auto_recall	bool	true	Attach vector matches to each prompt
memory.recall_limit	integer	5	Matches considered per prompt
memory.vector	table	none	Milvus connection; see Configuration
memory.embeddings	table	none	Embedding provider and model

With memory.enabled = false, the memory tools and the index disappear from every agent.