Knowledge

Build a knowledge base through conversation with Enso, then browse it in the read-only web viewer. The source of truth is ordinary Markdown on your machine: portable files you can keep, back up, and use with other tools. You do not need to write them yourself.

Use Memory for dated requests, decisions, and reported outcomes from past conversations. Knowledge holds maintained reference; Memory stores episodes in the database, with links to their original exchanges.

Availability

This guide describes the knowledge implementation in Enso’s beta source. The shared knowledge browser, enso knowledge commands, and enso-knowledge skill are not included in v0.1.2, the latest published release checked on September 15, 2026. Existing releases already have workspace knowledge/ directories and basic file browsing.

Run enso knowledge --help to check whether your installation includes this feature. If the command is unknown, use a release that includes it when available or an intentionally installed development build. A normal managed update installs published releases; it does not install unreleased development work.

Start with a conversation

Ask for the knowledge you want to keep:

Save what we learned about choosing a home router in shared knowledge. Link it to the existing home network page and keep the sources beside the claims.

For material that belongs to one workspace:

Keep the deployment checklist in the website workspace’s knowledge. Update the existing page, and link to our shared domain reference instead of copying it.

Enso loads the bundled enso-knowledge skill, finds the relevant pages, and maintains their files and metadata. A useful page has one home; other pages link to it. Detailed facts belong in knowledge, while brief rules about when to consult them belong in AGENTS.md. See instructions and skills.

Open Knowledge in the web viewer, or visit /knowledge at your viewer’s address. Choose General, a workspace, or All knowledge:

• Folders shows immediate subfolders and pages together. Follow the breadcrumbs to move back up; the reader also shows other pages in the same folder.
• Search looks through filenames and contents in the selected folder and everything below it. Choose All knowledge to broaden the search across roots.
• All notes gives a flat list; Recent shows recently updated files. Lists are paginated, so a collection with thousands of pages does not expand into one huge tree.
• Open a page to follow its links, see Linked from backlinks, or inspect View source.

The viewer has no editor. Continue the conversation to change a page, and reload the viewer to see saved changes. Browser back, forward, and opening links in another tab work normally. Keep remote access behind a private connection.

Shared and workspace knowledge

The default layout is:

~/.enso/
├── knowledge/                       # General: useful across workspaces
│   ├── Home network.md
│   └── Reference/
│       ├── Domains.md
│       └── Networking/
│           └── Choosing a router.md
└── workspaces/
    └── website/
        └── knowledge/               # Context owned by this workspace
            └── Deployment.md

Use your ENSO_HOME in place of ~/.enso if you configured another home.

Enso discovers existing workspace knowledge directories automatically, without a second registration or a viewer restart. Setup and managed upgrades that include this feature create a missing shared directory. enso workspace audit --fix can also create it; existing contents are preserved.

Folders can contain both pages and more folders. Keep them when they help explain the subject: Reference/Networking/ supplies context that a flat filename cannot. A flat collection works too. Start with the structure you already understand and reorganize when there is a concrete benefit.

Folders help an agent choose what to read; they do not automatically load every page or restrict file access. Workspace permissions apply separately. Keep attachments beside their related pages, and use links across roots instead of maintaining several copies of the same reference.

Links and attachments

Use familiar wiki links or ordinary Markdown links:

[[Home network]]
[[Reference/Domains|Domain reference]]
[[Deployment#Before you start]]
[Deployment checklist](../Deployment.md#before-you-start)
[[general:Reference/Domains|Shared domains]]
[[workspace:website:Deployment|Website deployment]]

The text after | is a display label. It does not add an alias or another metadata field to the target page. A bare wiki name must be unique in its root; Enso does not search other workspaces to guess its meaning.

Wiki paths are checked relative to the source folder and the knowledge root. If neither matches, a unique trailing path can resolve too: [[Networking/Choosing a router]] can find Reference/Networking/Choosing a router.md. Multiple matches stay visibly ambiguous. Use general: or workspace:<name>: with the full root-relative path to choose a target explicitly. Ordinary Markdown paths are relative to the page containing the link.

Heading links open the corresponding section. Missing targets and headings are flagged; Enso does not silently send you to another page. Each managed page has a unique ID, so its viewer URL survives a rename. Ask Enso to move it with enso knowledge move to repair file links as well: the move rewrites only the links it would otherwise break, and leaves links that still reach the same page exactly as written. It stops and explains itself when an incoming link to the page is ambiguous, or when a page it must repair has invalid metadata. Fix that first: give the ambiguous link an explicit general: or workspace:<name>: target, or run enso knowledge adopt on the page whose metadata is invalid. A direct filesystem rename keeps the ID but does not repair those paths.

Local images can use ![Network diagram](diagram.png) or ![[diagram.png]]. PNG, JPEG, GIF, WebP, and AVIF files display in the page; every other local attachment, including SVG, becomes a download link. A note embed such as ![[Home network]] becomes a link to that page rather than inserting its entire contents. External web and email links remain external; remote images are not loaded automatically.

The reader accepts .md pages up to 2 MiB and serves attachments up to 20 MiB. Hidden files, symbolic links, node_modules, __pycache__, and files outside the knowledge roots are excluded. Raw HTML is escaped; the reader does not execute a page’s scripts or user-defined formatting tools.

Minimal metadata

Enso keeps a small YAML block, called frontmatter, at the start of every managed page:

---
schema: enso.note/v1
id: 3d6d560a-21ef-49fa-a4db-7640b8dcab89
created: "2026-09-15T12:00:00Z"
updated: "2026-09-15T12:00:00Z"
---

## Before you start

The checklist goes here.

Enso writes timestamps in UTC with a timezone. An imported file’s modification time does not prove its original creation or content-update date, so unknown dates stay absent. A move updates updated when it repairs the page’s links; a move with no body change leaves that time alone.

These four fields are the whole metadata contract. Titles come from filenames. There are no type, tags, or custom metadata fields in this version. Put publication dates, sources, people, and other useful context in the body near the relevant information. Enso creates IDs for you; never reuse the example ID or copy a template’s ID into a new page.

Consistent formatting

The bundled skill supplies one writing style for General and every workspace:

Ask Enso to change the rules and checker together when you want a different style:

Use the filename as the title, start sections with ##, and use #### for subsections. Apply that style to shared and workspace knowledge.

That is a personal preference, not a fixed Enso requirement. The shipped checker checks line endings, final newlines, trailing whitespace, repeated blank lines, and spacing around headings. It leaves code and frontmatter alone and does not enforce H1 headings, a heading hierarchy, or a maximum line length.

User edits to the skill and its support files are preserved by managed upgrades. Change a convention because you want it changed, not just to silence a failed check. Core metadata, IDs, link validity, and file-access rules remain fixed in Enso and cannot be weakened by editing the style checker.

To check saved work with the default home:

enso knowledge audit --scope general
python3 ~/.enso/skills/enso-knowledge/scripts/lint.py ~/.enso/knowledge

Without --scope, the core audit checks all discovered roots. Run the style checker on the changed files or directories; it also accepts several paths. Both checks report problems without editing pages. Resolve uncertain links from their source context rather than inventing a destination to make the report clean.

Import an existing collection

An existing Markdown vault can keep its folders, pages, and attachments. Ask Enso to import a copy first, inspect the result, and then agree on any restructuring.

From an Enso source checkout that includes this feature:

uv run python scripts/import-knowledge.py /path/to/markdown-collection \
  ~/.enso/knowledge --receipt ~/enso-import-receipt.json

The destination must be absent or empty. The importer copies visible regular files, preserves nested folders and attachments, and skips hidden entries and symbolic links. It stages the copy before publishing it and leaves the original collection untouched. The receipt path must be outside both roots and must not already exist; keep it for the file hashes and skipped-entry list.

The script adds core metadata without inventing dates or rewriting prose and filenames. Unfamiliar or invalid frontmatter is kept in a fenced Imported metadata section. If the frontmatter has no closing delimiter, the entire original file is retained in a fenced Imported document section for review. Templates remain reference pages: create each new page with its own metadata and use only the template’s body structure.

Existing pages without valid metadata remain readable by path. To adopt one already inside a knowledge root:

enso knowledge adopt "Reference/Domains.md" --scope general
enso knowledge audit

Review imported links and run your style checker. Folders, ambiguous links, unsupported plugin syntax, and formatting preferences may need a separate, deliberate cleanup. The importer does not reproduce an editor’s plugins, graph view, or embedded-note rendering.

When Enso becomes your source of truth, update the old locations in its home/workspace instructions, installed skills, scheduled jobs, backup scripts, and stored file paths. The importer copies knowledge files; it does not redirect those automations for you. Choose which original files to retain and how to back up the new roots before retiring another writing workflow.

CLI and reliable writes

Most people can leave these details to Enso. The CLI reference lists the commands for scripts and direct use:

enso knowledge roots
enso knowledge list --scope general --folder Reference
enso knowledge search "domain renewal" --scope general --folder Reference
enso knowledge show "Reference/Domains.md" --scope general --json
enso knowledge move "Home network.md" "Reference/Networking/Home network.md" --scope general

list and search return up to 50 notes per page; --limit allows 1 to 500, and --offset skips earlier results. show --json returns the content and its sha256 revision. update requires that hash with --expected-hash, so an edit based on an older copy is refused. create and update take a file containing the Markdown body, or - for standard input; Enso manages the frontmatter. New destinations are never overwritten. adopt and move can also take an expected hash, and move --to-scope sends a page to another root.

Moves preserve original files for recovery while repairing links. If a move is interrupted, keep any .knowledge-move-* recovery directory in the Enso home and ask Enso to inspect its manifest and current file hashes before finishing or reversing it. Several linked files cannot all change in one filesystem operation; avoid editing those files with another tool during a move. Keep regular backups of shared and workspace knowledge.