How the DeepSeek-Reasonix Agent Memory System Stores, Retrieves, and Forgets Facts

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, 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/<slug>/memory/

The Store.Save method in 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 by appending a line such as:

- [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, 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 implements a soft-delete strategy to maintain auditability.

The Archive Process

When invoked, Store.Archive moves <name>.md from the active memory directory into a hidden .archive/ subdirectory, renaming it with a UTC timestamp using the layout 20060102-150405.000-<name>.md. Simultaneously, flushIndexIn removes the corresponding entry from 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 index.
• Retrieval: The memory tool uses BM25 search over concatenated metadata in 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/<slug>/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, 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}