Why AI Agents Lose Their Memory And How MemoFS Solves It

MemoFS, a new open-source tool, solves AI agent amnesia by storing agent memories as plain Markdown and JSON files in a project's .memofs/ directory, replacing unreliable context windows and vector databases. The system provides durable, inspectable, and versioned memory with features like PII redaction, supersedes graph edges, and hybrid search combining BM25 and vector embeddings. MemoFS works offline and integrates with agents via MCP, CLI, and API.

Whether you are using off-the-shelf AI coding tools like Claude Code and Cursor or building custom autonomous AI agents with TypeScript and LLM APIs, you hit the exact same fundamental wall: AI agent amnesia . As an agent user , you spend forty-five minutes explaining your architecture, deployment quirks, and database rules. The agent writes brilliant code. You close the CLI or tab, open a new session the next morning, and the agent suggests the exact legacy library you rejected yesterday. As an agent builder , you struggle to keep your custom agentic loops focused. As multi-step agent trajectories expand, LLM token limits force context compaction, wiping out subtle rules and past decisions while escalating API costs. The intelligence is real. The amnesia is structural. The AI industry’s standard reflex to agent amnesia has been pushing context windows to 1M+ tokens. But a context window is working memory RAM , not long-term storage disk . Relying on massive context windows introduces three critical engineering bottlenecks for both users and builders: Agents do not need larger transcripts. They need a durable, inspectable, versioned memory layer . When developers and AI engineers realize raw context windows aren't enough, the second reflex is to deploy a vector database. While vector search is excellent for passage retrieval in static documentation, it creates major friction when used for coding agents and local agent runtimes: cat or grep a vector database. When an agent acts on incorrect memory, neither the user nor the framework builder can easily inspect, diff, or debug what it remembered. MemoFS https://docs.memofs.dev is built on a fundamental insight: plain files are the optimal storage primitive for AI agent memory. Instead of hiding memory inside remote databases or proprietary dashboards, MemoFS stores all agent memories as plain, structured Markdown and JSON directly within your project's .memofs/ directory. .memofs/ .memofs/ ├── memory/ │ ├── core.md Always-on briefing project rules, stack, active constraints │ └── notes.md Long-form durable records decisions, summaries, rationale ├── events/ │ ├── memory-events.jsonl Append-only audit trail of all memory writes │ └── conversations.jsonl Session interaction logs ├── indexes/ │ ├── chunks.jsonl Tokenized text chunks │ └── embeddings.jsonl Derived local vector index BM25 + vector hybrid ├── graph/ │ ├── nodes.jsonl Entities & concepts │ └── edges.jsonl Relationships & supersedes links └── snapshots/ └── snapshots.jsonl Versioned checkpoints for instant rollback MemoFS transforms plain files into an intelligent memory engine through six structural disciplines: In MemoFS, markdown and JSON files under .memofs/ are the single source of truth. The full-text index, vector embeddings, and entity graph are derived artifacts . If an index is corrupted or an embedding model changes, running npx memofs doctor instantly rebuilds the entire search layer from raw files with zero data loss. Memory quality is determined at write time. Before any memory lands on disk, MemoFS executes: sk-... , credentials, and tokens up front. supersedes Graph Edges When project requirements change, old memories become stale. Deleting them loses context; keeping them creates contradictions. MemoFS links updated memories to older records using supersedes graph edges. When queried, the engine surfaces the current rule while keeping the historical decision chain intact. MemoFS fuses three search signals for every query: Out of the box, local mode operates completely offline with zero API keys using lexical BM25 and fuzzy string matching. When enabled, local ONNX embeddings upgrade the system to full hybrid recall without cloud dependencies. MemoFS connects to agents through three complementary mechanisms to serve both end users and agent builders: memofs.context , memofs.remember for Cursor, Copilot, Windsurf, and Gemini CLI. @memofs/core provides direct TypeScript APIs memo.context , memo.writeMemory for custom agent loops and autonomous multi-agent systems.Because memory lives in git-tracked text files, every memory write is diffable, reviewable in pull requests, and forensically traceable. If an untrusted source attempts memory poisoning, developers can run git diff .memofs/ to inspect and revert the change instantly. 1. Install MemoFS CLI npm install -g @memofs/cli 2. Initialize .memofs/ in your repository npx memofs init 3. Generate hooks / MCP config for your agent npx memofs generate agent claude --project-name "My App" or Codex npx memofs generate agent codex --project-name "My App" --scope local or for Cursor / Copilot / IDEs, e.t.c: npx memofs generate agent cursor @memofs/core SDK js import { MemoFS } from "@memofs/core"; import { createNodeFsMemoryStore } from "@memofs/core/node-fs"; // Initialize durable workspace memory in your agent framework const memo = new MemoFS { store: createNodeFsMemoryStore { rootDir: "." } , projectId: "custom-agent", mode: "local", } ; // Inject task-aware memory briefing into system prompt const context = await memo.context { query: userTask, taskType: "coding" } ; console.log context.text ; // Persist facts learned during execution await memo.writeMemory { content: "Auth uses JWT with Argon2id", kind: "decision" } ;