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 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.
npm install -g @memofs/cli
npx memofs init
npx memofs generate agent claude --project-name "My App"
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)
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" });