Nowledge FS

Nowledge FS is Mem's preview path-first layer for humans, agents, and scripts.

In the app, people meet it as Knowledge Tree: everything you know appears in one familiar tree. Memories, conversations, wiki pages, Working Memory, activities, sources, and artifacts keep their native behavior. The tree is not a folder full of raw implementation files. It is a calm map over Mem itself, so you can open one thing, see the right preview, and keep moving.

Agents see the same map as a virtual filesystem. That is the important shift: a human can browse in the app, while a script or agent can list, read, search, recall, and update canonical writable objects by path.

When To Use It

Use Knowledge Tree when you want a sense of place.

• You remember that something exists, but not whether it was a memory, thread, wiki topic, or source.
• You want to scan by type, date, label, or topic without opening several different views.
• You want an agent to inspect nearby context before loading large objects.
• You want paths you can copy into a command, script, prompt, or MCP call.

If you are just asking one question, search is still fine. Knowledge Tree is for navigation, orientation, and controlled inspection.

First Useful Loop

1. Open Tree in the app sidebar.
2. Open one branch such as Memories, Threads, Wiki, Working Memory, Activities, or Artifacts.
3. Click one item. The preview should feel like the rest of Mem: memories open as memory context, threads as readable conversations, wiki pages as wiki pages, and activities as Timeline-style events.
4. If you use the CLI, run:

nmem fs ls /
nmem fs recall "what did we decide about auth?" --in /memories -k 5

A good result is not a long blob of text. It is a path you can inspect next:

nmem fs stat /memories/by-id/<id>.memory.md
nmem fs cat /memories/by-id/<id>.memory.md

How To Think About Paths

Paths are Mem addresses, not files on your disk.

/memories/by-id/<id>.memory.md
/threads/<source>/<thread>/messages.jsonl
/wiki/entities/<topic>.entity.md
/working-memory/today.md
/feed/2026-05-15/<event-id>.feed.jsonl
/artifacts/imports/<document>.artifact.pdf

Some paths are canonical. Those can be updated when the object itself is writable. Other paths are aliases, like a memory shown under a label or date branch. Aliases are there for browsing and should be edited through the canonical path.

What Agents Should Do

Agents should move through the tree in small steps:

1. Use recall for fuzzy memory questions.
2. Use find for structural constraints such as type, label, date, or mention.
3. Use grep for exact phrases.
4. Use stat before loading large objects.
5. Use cat only after a useful path has been found.

This keeps context small and makes the agent's work inspectable. You can see the same path in the app, the CLI, the API, or the MCP tool.

nmem fs recall "why did we change token refresh?" --in /memories -k 5
nmem fs ls /memories/by-label/auth
nmem fs cat /memories/by-id/<id>.memory.md

For long conversations and documents, agents should not load the whole file first. Search the branch, then read a small line window:

nmem fs grep "JWT rotation" /threads
nmem fs cat /threads/<source>/<thread>/messages.jsonl --line 42 --lines 12

nmem fs grep "rate limit" /sources
nmem fs cat /sources/<document>.pdf --line 120 --lines 80

Thread transcripts are JSONL: one line is one message. Parsed Library documents are rendered as markdown, so grep line numbers can be passed directly into cat --line.

In this preview, recall is memory-backed. Use grep for exact search inside threads and parsed Library documents.

MCP clients can use the same verbs through mem_fs. Codex, Claude, Cursor, Gemini, OpenClaw, and other agents are just consumers of this shared Mem shape; no single integration owns it.

The concrete entry points keep short host-friendly names: nmem fs in the CLI, /fs/* in the API, and mem_fs in MCP.

What Not To Worry About Yet

• You do not need to mount anything.
• You do not need to understand the graph schema.
• You do not need to choose between Tree and Library. Library remains the rich document and wiki reading surface; Tree gives you one map across all Mem objects.
• You do not need SQL or Cypher for the preview release. Those query surfaces belong to later phases after the safety limits and result shapes are pinned.

Success Check

Knowledge Tree is working when:

• the app shows the main branches without raw implementation files;
• clicking an item opens a native Mem preview, not a generic text dump;
• nmem fs ls / returns the same top-level idea as the app;
• nmem fs recall ... returns paths;
• web and remote clients can use the same /fs/* API shape as desktop.

Next