Designing Persistent Memory for LLMs with Storage and Retrieval: A Practical YAMS Guide

Long conversations eventually bury decisions, and a fresh session often starts with a costly re-explanation of the same project. The useful answer is not to pretend that a model remembers everything forever. It is to build an external memory layer that preserves source material and retrieves the right evidence when it is needed. YAMS is a local-first system that combines content-addressed storage with text, vector, graph, and grep-style retrieval. It is best understood as a way to keep documents and code findable—not as a substitute for checking the original source.

Treat memory as storage and retrieval

Durable project memory has three practical layers: source files and versions that can be checked later, metadata such as tags/projects/snapshots, and indexes that make recall possible. YAMS documents describe content-addressed storage, a SQLite/FTS5 metadata path, and a vector index for embeddings. Its retrieval pipeline can combine lexical, semantic, and structural signals. That combination is useful, but a search hit is still a lead, not proof. Keep the originating file path and snapshot with the result; before using a result in an answer or a change, reopen the source and verify the relevant passage.

Start small with a project-scoped store

Putting every personal note and every work repository into one index quickly makes retrieval noisy. A separate store per project gives both better recall and a clearer security boundary.

YAMS_STORAGE="$PWD/.yams" yams init --non-interactive
YAMS_STORAGE="$PWD/.yams" yams add README.md --tags "docs,project"
YAMS_STORAGE="$PWD/.yams" yams add src/ --recursive --include="*.ts,*.md" --tags "source"
YAMS_STORAGE="$PWD/.yams" yams search "deployment environment variables" --limit 5

The official quick start covers the same basic loop: add content, search it, retrieve it, and compare snapshots when needed. yams watch can help with automatic ingestion, but decide exclusion rules first. Secrets, personal information, generated artifacts, and vendored dependencies are rarely good default memory. More data is not automatically better data.

Semantic search is optional—and needs operations

YAMS can generate embeddings on add and, where the SQLite build supports it, index extracted text in FTS5. With both paths available, keyword and semantic retrieval can be fused. The documentation also notes that embedding and FTS operations are best-effort: failures can be logged and skipped so ingestion is not blocked. In other words, a successful keyword search does not prove that semantic indexing is healthy. Check yams status, yams doctor, and yams stats --verbose; use targeted repair commands such as yams repair --embeddings or yams repair --fts5 only after identifying what is missing.

Embedding dimensions must match the selected model’s output. Plan an index check or rebuild whenever that model changes. For quality, use a small set of real questions—perhaps 20 to 50—and measure whether the authoritative source appears near the top, rather than judging a system by a single plausible-looking answer.

Keep boundaries when connecting an LLM or MCP client

YAMS can expose an MCP server through yams serve, letting an agent search stored context. Returned documents should remain reference material, never instructions to execute by default. Preserve provenance, show freshness where it matters, and require an explicit review before an agent follows commands embedded in retrieved text. YAMS also documents a trust gate for plugins; do not casually trust an unknown binary plugin in a repository that contains sensitive work.

“Permanent memory” succeeds less through a model name than through disciplined records: scope what enters the store, tag it deliberately, write compact decision notes, and verify every retrieved claim against its source. That leaves a project with usable context even when the chat session is gone.

Primary source

https://yamsmemory.ai/user_guide/
https://yamsmemory.ai/architecture/system_architecture/