ls .memofs/The File-First Memory Runtime for AI Agents
Store decisions, facts, and context as simple markdown files in your project — versioned, portable, and always there when the next session starts.
The Problem
AI Agents memory is broken in two directions.
On one side, static markdown rulebooks like AGENTS.md, CLAUDE.md and .cursor/rules bloat context windows with massive token dumps that silently drift the moment project files, docs, data schemas, or implementations change.
On the other side, hosted vector databases lock learned facts inside proprietary black boxes, invisible, impossible to review in a git diff, disconnected from your project, and trapped in someone else's cloud.
Silent Project Drift.
When project files, schemas, docs, or code change, unanchored memories reference deleted assets and obsolete facts, turning into toxic ghost context that actively steers AI into hallucinations.
The Black-Box Silo.
Proprietary vector databases lock learned knowledge behind opaque APIs. You can't inspect what the AI learned, edit it in your local editor, or review it in a git diff alongside your project.
The Prompt-Bloat Dilemma.
Static rulebooks (like 50KB instruction files) burn thousands of prompt tokens on every turn, while AI models forget to query dynamic memory unless the runtime deterministically pushes it.
Runtimes
One engine, three storage modes
MemoFS is built on a unified store abstraction. Choose where your memory resides based on your workflow and access needs.
Local Storage Mode
All memory is stored directly on your project's filesystem as versioned markdown and JSON. Zero network latency, fully offline, and 100% git-trackable.
Hybrid Sync Mode
Sub-millisecond local execution with automatic cloud replication. Your agent memory follows you across multiple machines, desktop workstations, and teammates.
Hosted MCP Endpoint
MemoFS Cloud hosts the runtime directly. Remote agents, ephemeral CI/CD containers, and serverless bots connect via standard MCP endpoint URL and API key.
Features & Capabilities
Engineered for autonomous agent memory
From sub-millisecond local hybrid recall to self-healing project anchors and multi-agent coordination. Built with transparent files, deterministic logic, and zero black boxes.
Project Anchoring & Drift Detection
Memories bind directly to project files, research documents, data schemas, byte hashes, and symbol paths. When underlying assets change, query-time drift detection automatically demotes stale memory relevance before it causes hallucinations.
Hybrid Recall & Gated Fusion
Sub-millisecond BM25 lexical keyword matching fused with dense vector embeddings via bounded gated-bonus ranking. Unifies memory chunk identity to eliminate duplicate hits and avoid LLM context bloat.
Entity Graph & Causal Provenance
Extracts entities, relationships, and causal lineage (memofs why) into transparent nodes.jsonl and edges.jsonl files. Deterministic and critic-gated consolidation merges redundant facts and traces decisions back to source evidence.
AgentFS Workspace Scratchpads
Isolated scratch filesystem per agent turn with outcome-gated memory promotion (success, failure, aborted). Automatically preserves and promotes high-signal durable facts while pruning intermediate session noise.
Runtime Behavior Enforcement
Deterministic push hooks across 9+ AI tools and agent environments including Claude Code, Cursor, Copilot, Codex, and Gemini CLI. Automatically injects relevant memory context at session start, enforces project constraints, and preserves state across context compactions.
Cognitive Decay & Cold Archive
Memory-kind expiry windows age facts into unverified status without manual maintenance. Operator-guided consolidation moves superseded memories to cold archive with full forensic restoration.
Ephemeral Stream & Agent Pub/Sub
Real-time append-only stream for transient cross-agent coordination (heartbeats, file intent, task status) and human steering hints. Filtered out of durable recall to eliminate noise, with automated TTL garbage collection on maintenance runs.
Procedural Memory & Playbooks
Actionable step-by-step workflow recipes and standard operating procedures stored as human-readable Markdown and structured JSON. Context strategist dynamically matches and surfaces relevant playbooks based on task type.
Static Memory Linter
Semantic static analyzer CLI (memofs lint) for CI/CD pipelines. Detects contradictory assertions across stored notes, broken causal provenance links, dead project references, and orphaned knowledge graph entities before merge.
Visual Memory Studio
Local zero-dependency webview debugger for .memofs/. Inspect BM25 vs vector vs graph recall weight breakdowns, explore interactive entity graphs, and test snapshot rollback diffs in real time.
Vendor Memory Import & Setup
One command to bring your existing memory with you — import from developer tools, research agents, plus Mem0, Zep/Graphiti, Letta, and Cognee exports. Full offline file adapters write through the standard durable path with provenance and dry-run preview.
Immutable Action Receipts
Append-only audit receipts capturing consequential AI actions, task correlation, causal parentage, reversibility metadata, argument digests, and before/after snapshot hashes for complete execution accountability.
Why File-First
MemoFS vs. Black-Box Memory
Most memory tools hide your data in opaque remote databases or rely on static rule files that drift and bloat prompt context. MemoFS combines deterministic local execution, project-anchored verification, and git-native transparency.
| Dimension | MemoFS | Hosted Memory DBs |
|---|---|---|
| Where memory lives | ✓Plain Markdown & JSONL files in .memofs/ | ✕Locked in a proprietary cloud database |
| Project drift detection | ✓File hash, AST symbol & schema validation (memofs lint) | ✕None; stale memories reference deleted assets & data |
| Behavior enforcement | ✓Deterministic push hooks across 9+ AI tools & runtimes | ✕Passive pull tools; relies on model to remember to search |
| Causal lineage & audit | ✓Immutable action receipts & causal traversal (memofs why) | ✕Opaque similarity scores; ephemeral chat logs lost |
| Inspect & edit | ✓Any editor (VS Code, Cursor, Neovim, CLI) | ✕Vendor web dashboard or raw unindexed file |
| Version control | ✓Git-tracked & branchable alongside your project | ✕Separate external database decoupled from project history |
| Context efficiency | ✓Token-budgeted hybrid recall (BM25 + vector + graph) | ✕Monolithic prompt bloat or noisy top-k embeddings |
| Offline execution | ✓100% local-first; runs offline & in sandboxes | ✕Requires persistent network & cloud API keys |
| Multi-agent coordination | ✓Advisory file locks & standard stream schemas | ✕Unsynchronized writes or heavy external daemons |
One command. Your agent never forgets.
Get started in under 2 minutes. Install the CLI or import the SDK directly into your TypeScript project.