Core Concepts

MemoFS organizes agent memory into structured, project-scoped layers. By separating memory by retrieval frequency and purpose, the system prevents context bloat while preserving long-term intelligence.

The 11 Canonical Files Layout

Inside your workspace root, MemoFS manages all memory state in the .memofs/ directory across 11 canonical files:

.memofs/
├── manifest.json              # [1]  Tracked memory assets & anchor hash cache
├── memory/
│   ├── core.md                # [2]  Core canonical rules & baseline facts
│   └── notes.md               # [3]  Archival timestamped memory notes
├── events/
│   ├── memory-events.jsonl    # [4]  Append-only memory write/event audit log
│   └── conversations.jsonl    # [5]  Chronological conversation interaction log
├── indexes/
│   ├── chunks.jsonl           # [6]  Chunked text fragments for lexical recall
│   └── embeddings.jsonl       # [7]  Persisted vector embeddings
├── graph/
│   ├── nodes.jsonl            # [8]  Entity nodes (concepts, tools, decisions)
│   └── edges.jsonl            # [9]  Relationship triples & dependencies
├── snapshots/
│   ├── snapshots.jsonl        # [10] Checkpoint index
│   └── <snapshot-id>.json     # Dynamic snapshot checkpoints
├── connectors.json            # [11] External source connectors (no secrets)
├── archive/
│   └── <memory-id>.json       # Full-fidelity cold-archived memory records
└── tmp/                       # Temporary workspace scratch directory

Canonical Files Reference

Durability Tiers (durable vs transient)

When a memory is written via memofs.writeMemory(), MemoFS classifies its durability tier:

• durable: High-value facts, decisions, and constraints. Written to notes.md, recorded in memory-events.jsonl, and indexed into the recall index and knowledge graph so they steer future agent sessions.
• transient: Scratchpad observations, temporary working state, or low-confidence guesses. Written to notes.md and memory-events.jsonl as an audit trail, but never indexed into recall or graph. This prevents scratch thoughts from polluting prompt context.

Classification Decision Rules

The classifier evaluates signals in strict priority order:

Write Blocklist & Secret Safety

To prevent accidental leakage of credentials into syncable memory files, all writes through memofs.writeMemory(), memofs.core.update(), and memofs.agentfs.complete() pass through the Write Blocklist Gate (assertWriteAllowed):

• Zero-Config, Always-On: The blocklist runs locally with zero external network dependencies.
• Hard Rejection: Writes containing secret material throw MemoryWriteBlockedError immediately. Nothing is persisted.
• Safe Redaction: Error messages and violation previews contain only redacted snippets (first 3 characters + … + last character, e.g., sk-…z) — never full tokens.

Monitored Secret Patterns

The BLOCKLIST_RULES engine monitors five primary secret categories:

Code Anchoring & Drift Detection

Memories can be bound to source code files using an AnchorRef. This binds the memory to a repository-relative path and the file's SHA-256 content hash computed at write time:

// Explicit anchor
await memofs.writeMemory({
  title: "Auth Token Rotation",
  content: "Tokens are verified in src/auth/verify.ts using asymmetric RSA256.",
  kind: "decision",
  anchor: {
    file: "src/auth/verify.ts",
    hash: "a3f5b8...",
    symbol: "src/auth/verify.ts#verifyToken", // Optional AST symbol path
  },
});

Alternatively, use the inline marker syntax in note content:

We enforce strict JWT validation. @anchor(file="src/auth/verify.ts", symbol="verifyToken")

Drift Detection at Recall Time

When memofs.recall() or memofs.context() executes:

1. The recall engine consults the Anchor Hash Cache in .memofs/manifest.json (5-minute TTL with mtime invalidation).
2. If the anchored source file was modified or deleted on disk, the recalled item is flagged with stale: true.
3. Stale memories receive an automated 50% relevance score demotion (score *= 0.5).
4. Stale items are still returned (rank-demoted rather than hidden) so agents are informed that the underlying code has drifted.

Memory Decay Floors

Knowledge naturally ages. To prevent obsolete decisions from being trusted indefinitely, MemoFS assigns kind-specific decay floors via EXPIRY_DAYS:

When a memory exceeds its expiry floor:

• The item is flagged with unverified: true.
• It receives a 40% score demotion (score *= 0.6 — milder than code drift).
• Surfacing unverified memories signals to agents that human or automated re-verification is warranted.

Knowledge Graph & Fact Statuses

MemoFS includes an entity-relationship graph stored in graph/nodes.jsonl and graph/edges.jsonl.

Graph Fact Statuses

Every node and edge maintains a status:

Orthogonal Flags

Nodes and edges also carry orthogonal boolean flags that do not override the primary status:

• disputed: boolean: True when contested by conflicting facts.
• stale: boolean: True when the bound code file has drifted.
• unverified: boolean: True when fact age exceeds its kind-specific floor.

Memory Archive & Restore Lifecycle

Deprecated memories can be moved out of active memory into cold storage (.memofs/archive/<id>.json) using memofs.archiveDeprecated():

1. active → deprecated: Consolidation identifies an edge A supersedes B and transitions fact B to deprecated.
2. deprecated → archived: memofs.archiveDeprecated() moves the deprecated note to .memofs/archive/<id>.json and removes it from notes.md. Bound graph nodes transition to archived.
3. archived → active: memofs.restoreMemory(id) reads the archive file, re-inserts the note into notes.md, reactivates the graph node, and deletes the archive JSON.

Progressive Context Retrieval

Instead of dumping the entire memory store into an LLM prompt, MemoFS uses a 4-Stage Strategist Retrieval Pipeline:

1. Rewrite: Tokenizes the query, appends task-specific lexicon which defaults to general, and expands synonyms.
2. Resolve: Looks up matching entities in the knowledge graph and computes active neighbor subgraphs.
3. Filter: Applies code drift demotions, decay demotions, and suppresses retired entities.
4. Budget: Slices sections according to target byte limits and weights, generating progressive expansion cursors:

export const SECTION_WEIGHTS = {
  recall: 3,
  entities: 2,
  recent: 1,
  notes: 1,
} as const;