Memory Layer

Relevant source files

• DOCKERHUB.md
• deploy/local/README.md
• deploy/remote/README.md
• src/vault-mcp/mcp-core/tools/memory-tools.ts
• src/vault-mcp/obsidian-markdown/__tests__/memory-entries.test.ts
• src/vault-mcp/obsidian-markdown/memory-entries.ts
• src/vault-mcp/vault-operations/__tests__/memory-store.test.ts
• src/vault-mcp/vault-operations/memory-store.ts
• templates/memory/Agents.md
• templates/memory/Me.md
• templates/memory/Opinions.md
• templates/memory/Principles.md
• templates/memory/README.md
• templates/memory/Routines.md

The Memory Layer is a specialized subsystem designed to provide AI agents with long-term, structured context about the user. It moves beyond simple file access by enforcing a specific markdown schema—dated bullet entries within H2 sections—enabling agents to read, append, and evolve personalized context such as principles, opinions, and identity facts.

This layer also handles Daily Note resolution by bridging Obsidian's internal configuration with the filesystem, allowing agents to seamlessly interact with the user's journaled activity. The layer is active by default but can be disabled via the MEMORY_ENABLED environment variable src/vault-mcp/server.ts77-80

Memory Store Architecture

The memory system is built around the concept of "About Me" files. These files are not just flat text; they are structured logs where each entry is anchored by a date. This design ensures temporal context, allowing agents to weigh recent preferences over older ones and track the evolution of the user's stances over time templates/memory/README.md96-116

Data Structure: Dated Bullets

Memory files follow a strict structural contract templates/memory/README.md30-43:

• H1 Heading: The file title (one per file) src/vault-mcp/vault-operations/memory-store.ts162-163
• Scope Callout: An Obsidian > [!info] Scope of this file block describing the file's purpose. Surfaced by listMemoryFiles to provide agents with a high-level orientation src/vault-mcp/vault-operations/memory-store.ts112
• H2 Headings: Thematic sections, canonically suffixed with (newest first) src/vault-mcp/vault-operations/memory-store.ts71-74
• Dated Entries: Lines starting with - **YYYY-MM-DD**: src/vault-mcp/vault-operations/memory-store.ts47

Entry Policies

Memory files define maintenance behavior via entry-policy frontmatter src/vault-mcp/vault-operations/memory-store.ts98-105:

• append-only (Default): Entries are never edited or deleted; corrections arrive as new dated entries src/vault-mcp/vault-operations/memory-store.ts92-93
• living: Current-state snapshots (e.g., Routines.md). Expired entries are pruned rather than left as history src/vault-mcp/vault-operations/memory-store.ts94-97

Safety Mechanisms

To prevent data loss in a remote, concurrent environment, the memory-store.ts implementation includes critical safeguards:

1. File Write Locks: Uses withFileLock to serialize concurrent updates to the same memory file src/vault-mcp/vault-operations/memory-store.ts11
2. Shrink Guard: The guardAgainstShrink function refuses any write that would reduce a file's size by more than 50% (if the file is over 1250 bytes). This prevents skeleton templates from accidentally overwriting established memory src/vault-mcp/vault-operations/memory-store.ts28-43
3. Idempotency & Format Guard: The system rejects entries containing line breaks to prevent format corruption src/vault-mcp/vault-operations/memory-store.ts49-51 It performs an exact-bullet check to prevent duplicate entries during retries src/vault-mcp/vault-operations/memory-store.ts333-335
4. Path Validation: Memory files must be bare names. The store rejects any file name containing path separators to prevent directory traversal src/vault-mcp/vault-operations/memory-store.ts192-198

Implementation Mapping: Memory Logic

The following diagram maps natural language operations to the internal MemoryStore functions.

Natural Language to Code Entity Space: Memory Operations

Sources: src/vault-mcp/vault-operations/memory-store.ts1-43 src/vault-mcp/vault-operations/memory-store.ts160-181 src/vault-mcp/vault-operations/memory-store.ts265-357

---

Entry-Granular Hybrid Retrieval

While standard search operates on whole notes or headings, the memory layer provides entry-granular retrieval by parsing individual bullets into a dedicated index.

Indexing and Reconciliation

Dated entries are parsed individually by memory-entries.ts src/vault-mcp/obsidian-markdown/memory-entries.ts99-175 and stored in the search index.

• Grammar Parser: parseMemoryEntries walks H2 section spans, identifying the ENTRY_START_PATTERN (- **YYYY-MM-DD**:) while remaining aware of code fences and comments to avoid false positives src/vault-mcp/obsidian-markdown/memory-entries.ts47 src/vault-mcp/obsidian-markdown/memory-entries.ts137-143
• Continuation Logic: Every line after an entry's bullet—including wrapped prose, sub-bullets, and fenced code—is absorbed as continuation text until the next entry or section boundary src/vault-mcp/obsidian-markdown/memory-entries.ts89-92
• Recall Index: These entries are stored in the memory_entries table, enabling vault_memory_recall to retrieve relevant dated entries across all memory files at once src/vault-mcp/mcp-core/tools/memory-tools.ts13 templates/memory/README.md83

Sources: src/vault-mcp/obsidian-markdown/memory-entries.ts1-175 src/vault-mcp/mcp-core/tools/memory-tools.ts1-140

---

Daily Notes Support

Vault Cortex provides native support for Obsidian Daily Notes by reading the vault's internal configuration from .obsidian/daily-notes.json src/vault-mcp/vault-operations/daily-notes.ts74-79

Configuration & Resolution

The daily-notes.ts module performs a translation between Moment.js tokens (used by Obsidian) and Luxon tokens (used by the server) to resolve file paths accurately.

Feature	Implementation Detail
Format Conversion	momentToLuxonFormat() converts tokens like YYYY to yyyy and handles bracketed literals [Daily Note] via MOMENT_ESCAPE_RE src/vault-mcp/vault-operations/daily-notes.ts37-53
Config Caching	The .obsidian/daily-notes.json is read and cached in cachedConfig to minimize I/O src/vault-mcp/vault-operations/daily-notes.ts72-80
Path Resolution	getDailyNotePath() combines the configured folder and formatted date to find the .md file src/vault-mcp/vault-operations/daily-notes.ts119-141

Natural Language to Code Entity Space: Daily Note Resolution

Sources: src/vault-mcp/vault-operations/daily-notes.ts1-171

---

Opt-out and Initialization

The memory layer is entirely opt-out via environment variables.

MEMORY_ENABLED=false

When MEMORY_ENABLED is set to false:

1. Tool Stripping: The server skips registration of memory tools in mcp-router.ts src/vault-mcp/server.ts100-103
2. Bootstrap Skip: The server skips bootstrapMemoryDir during startup src/vault-mcp/server.ts102
3. Index Exclusion: The search index excludes memory-specific directories from the rebuild src/vault-mcp/server.ts91-93

Bootstrapping

On first startup (if enabled), bootstrapMemoryDir initializes the MEMORY_DIR (default: About Me/) and populates it with foundational templates src/vault-mcp/vault-operations/memory-store.ts101-102:

• Me.md: Identity, interests, and durable context templates/memory/Me.md1-29
• Principles.md: Stable values and decision heuristics templates/memory/Principles.md1-28
• Opinions.md: Evolving views on tools and workflows templates/memory/Opinions.md1-28
• Routines.md: Recurring cadences and habits; uses entry-policy: living templates/memory/Routines.md1-29
• Agents.md: Directives specifically for AI agents templates/memory/Agents.md1-28

Sources: src/vault-mcp/server.ts77-103 src/vault-mcp/vault-operations/memory-store.ts98-114 templates/memory/README.md1-60