# How the DeepSeek-Reasonix Agent Memory System Stores, Retrieves, and Forgets Facts > Discover how DeepSeek-Reasonix agent memory stores facts as Markdown, retrieves context with BM25, and archives outdated information for efficient AI reasoning. - Repository: [YHH/DeepSeek-Reasonix](https://github.com/esengine/DeepSeek-Reasonix) - Tags: internals - Published: 2026-06-22 --- **The DeepSeek-Reasonix agent implements a file-based auto-memory system that writes facts as Markdown files to disk, retrieves relevant context using BM25 search, and archives obsolete facts with timestamps rather than permanent deletion.** The Reasonix agent in the `esengine/DeepSeek-Reasonix` repository maintains a human-readable **agent memory system** that requires no external databases or embeddings. This pure Go implementation stores facts as individual Markdown filesunder version-controllable paths, indexes them in a central manifest for fast lookup, and manages memory lifecycle through idempotent write, search, and archive operations. ## Storing Facts: The `remember` Tool and File Structure The `remember` tool, defined in [`internal/memory/remember.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/memory/remember.go), persists each fact as a standalone Markdown file with YAML front-matter. The process combines atomic file writes with index updates to ensure the agent’s working context stays synchronized with the filesystem. ### Memory File Format and Storage Locations Each memory file contains a front-matter header specifying `name`, `title`, `description`, and `metadata.type`, followed by the free-text fact body. The storage location depends on the memory type: - **Global memories** (`user`, `feedback`) → `~/.reasonix/memory/global/` - **Project memories** (`project`, `reference`) → `~/.reasonix/projects//memory/` The `Store.Save` method in [`internal/memory/store.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/memory/store.go) handles path resolution and writes the file atomically. ### Index Management and Caching After persisting the Markdown file, `Store.Save` updates [`MEMORY.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/MEMORY.md) by appending a line such as: ```markdown - [My Fact](my-fact.md) — short description ``` This index is loaded into the **system-prompt prefix** at session startup. Consequently, the model receives a complete manifest of active memories without filesystem thrashing on every turn, while the human-readable Markdown remains editable outside the agent. ## Retrieving Facts: BM25 Search and Session History The agent exposes two read-only tools for recall, operating exclusively on *active* memories and ignoring archived files. ### The `memory` Tool and BM25 Ranking Implemented in [`internal/memory/recall.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/memory/recall.go), the `memory` tool performs BM25 ranking over a concatenated text field containing the memory’s `name`, `title`, `type`, `description`, and `body`. High-scoring results can be passed to the `read` action to fetch the full Markdown content or to `list` to enumerate all active memories. ### Session Transcripts with the `history` Tool For exact wording of prior turns, the `history` tool (located in `internal/history`) searches the session transcript, including user utterances, assistant responses, and tool errors. This complements the semantic memory store by providing temporal context when specific phrasing matters more than conceptual similarity. ## Forgetting Facts: Archiving Instead of Deletion The `forget` tool in [`internal/memory/forget.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/memory/forget.go) implements a soft-delete strategy to maintain auditability. ### The Archive Process When invoked, `Store.Archive` moves `.md` from the active memory directory into a hidden `.archive/` subdirectory, renaming it with a UTC timestamp using the layout `20060102-150405.000-.md`. Simultaneously, `flushIndexIn` removes the corresponding entry from [`MEMORY.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/MEMORY.md). Because the system-prompt prefix only reflects the active index, the forgotten fact immediately ceases to influence future reasoning, yet remains recoverable by listing archived files via `store.ListArchived()`. ## Security Boundaries and Path Sanitization All filesystem operations are guarded by `safeJoin` sanitization, ensuring the memory store is strictly confined to the user’s home directory. No absolute or relative path escapes are permitted, preventing directory traversal attacks even when processing untrusted memory names. ## Summary - **Storage**: The `remember` tool writes Markdown files with front-matter to project-specific or global directories and updates the [`MEMORY.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/MEMORY.md) index. - **Retrieval**: The `memory` tool uses BM25 search over concatenated metadata in [`internal/memory/recall.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/memory/recall.go), while `internal/history` handles session transcripts. - **Forgetting**: The `forget` tool archives files to `.archive/` with timestamps via `store.Archive`, removing them from the active index without permanent deletion. - **Architecture**: File-based storage with path sanitization (`safeJoin`) eliminates external dependencies while maintaining human readability. ## Frequently Asked Questions ### How does the agent decide whether to store a memory globally or within a project? The decision is based on the memory’s `metadata.type` field. Types `user` and `feedback` are routed to the global directory (`~/.reasonix/memory/global/`), whereas types `project` and `reference` are saved under the specific project path (`~/.reasonix/projects//memory/`). This scoping ensures user preferences persist across sessions while project-specific references remain coupled to their codebase. ### What search algorithm powers the memory retrieval? The `memory` tool implements **BM25** ranking, a probabilistic retrieval model that scores documents based on term frequency and inverse document frequency. The searchable corpus is dynamically built from the `name`, `title`, `type`, `description`, and `body` fields of all active memory files, making concise, descriptive titles critical for accurate lookup. ### Can archived memories be permanently deleted or restored? The current implementation moves forgotten memories to the `.archive/` subdirectory with UTC timestamps but does not provide an automatic purge mechanism. Archived files remain on disk for auditability and can be listed or manually restored by moving the file back to the active directory and updating [`MEMORY.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/MEMORY.md), though the agent itself currently exposes no `restore` tool. ### Is there a limit to how many active memories can be indexed? While the codebase does not enforce a hard limit on active memory files, the entire [`MEMORY.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/MEMORY.md) index is loaded into the system-prompt context at session start. Extremely large indices could impact token consumption and latency, so the architecture implicitly encourages archiving obsolete facts to keep the working set lean.