Nowledge FS API
Preview API for Tree, nmem fs, and agent integrations.
The Nowledge FS API is the preview API behind Knowledge Tree. It projects Mem as a stable tree and is the same surface used by the app's Tree view, the nmem fs CLI, and the mem_fs MCP tool.
Use it when an integration or agent should browse memories, threads, wiki pages, working memory, activities, sources, and artifacts through paths.
Initial release scope
This is not a mounted filesystem yet. Paths are Mem API identifiers, not local OS paths. Mounting, source fragments, SQL/Cypher, replay, and tail are planned for later phases.
Read
curl "http://127.0.0.1:14242/fs/capabilities"
curl "http://127.0.0.1:14242/fs/ls?path=/"
curl "http://127.0.0.1:14242/fs/cat?path=/memories/by-id/mem_abc.memory.md"
curl "http://127.0.0.1:14242/fs/cat?path=/sources/report_abc.pdf&line=120&lines=80"
curl "http://127.0.0.1:14242/fs/stat?path=/memories/by-id/mem_abc.memory.md"| Endpoint | Purpose |
|---|---|
GET /fs/capabilities | Discover supported roots, verbs, limits, entry points, and feature flags. Use this before writing adapters. |
GET /fs/ls?path=/...&limit=200&cursor=... | List a directory. Cursors are opaque. |
GET /fs/cat?path=/...&line=...&lines=... | Read a rendered file body and frontmatter, or a small line window. |
GET /fs/stat?path=/... | Read metadata without loading the body. |
Search
curl "http://127.0.0.1:14242/fs/find?path=/memories&type=memory&label=decisions"
curl "http://127.0.0.1:14242/fs/grep?path=/memories&q=JWT%20rotation"
curl "http://127.0.0.1:14242/fs/grep?path=/threads&q=JWT%20rotation"
curl "http://127.0.0.1:14242/fs/grep?path=/sources&q=JWT%20rotation"
curl "http://127.0.0.1:14242/fs/grep?path=/threads&q=JWT%7Ctoken®ex=true"
curl "http://127.0.0.1:14242/fs/recall?path=/memories&query=session%20token%20strategy&k=5"| Endpoint | Purpose |
|---|---|
GET /fs/find | Structural search. Use this for type, label, date, and mention constraints. |
GET /fs/grep | Exact-string search over memories, thread messages, and parsed Library documents. Add regex=true for regex. |
GET /fs/recall | Semantic search that returns paths. |
find and recall return paths. grep returns matches with paths and line numbers. Grep is case-insensitive by default; pass case_sensitive=true when casing matters, or regex=true for patterns such as JWT|token. Agents should feed returned paths into stat, ls, or cat; for long files, use cat with line and lines to read only the useful window.
Write
curl -X POST "http://127.0.0.1:14242/fs/write" \
-H "Content-Type: application/json" \
-d '{"path":"/memories/by-id/mem_abc.memory.md","body":"Updated note"}'
curl -X POST "http://127.0.0.1:14242/fs/delete" \
-H "Content-Type: application/json" \
-d '{"path":"/memories/by-id/mem_abc.memory.md"}'Writes are deliberately narrow. Canonical writable paths write through the existing Mem APIs. Alias paths, derived wiki pages, and implementation views are read-only.
| Code | Meaning |
|---|---|
ENOENT | Path does not exist. |
EROFS | Derived path is read-only. |
EXDEV | Alias path cannot be written directly; use the canonical path. |
EINVAL | Invalid path, argument, or body. |
ENOTSUP | Designed but not implemented in this release. |
Agent pattern
recall "what did we decide about auth?" --in /memories
cat /memories/by-id/<id>.memory.md
ls /memories/by-label/auth
stat /wiki/entities/PostgreSQL--<id>.entity.mdThe important property is that every result is navigable. Search is an entry point into the tree, not a terminal list of snippets.