# 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](/docs/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](https://github.com/geekforbrains/enso/releases/tag/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](/docs/customizing/).

Open **Knowledge** in the [web viewer](/docs/web/), 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](/docs/web/#access).

## Shared and workspace knowledge

The default layout is:

```text
~/.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.

| Location | Put here | CLI scope |
| --- | --- | --- |
| `$ENSO_HOME/knowledge/` | Shared reference, personal knowledge, and facts used across workspaces | `general` |
| `$ENSO_HOME/workspaces/<name>/knowledge/` | Reference whose context belongs to one workspace | `workspace:<name>` |

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](/docs/security/) 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:

```markdown
[[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:

```markdown
---
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.
```

| Field | Required? | Meaning |
| --- | --- | --- |
| `schema` | Yes | Exactly `enso.note/v1`, identifying this format |
| `id` | Yes | A unique UUID that identifies the page through moves and renames |
| `created` | Added to new pages; optional on imports | When the page was created |
| `updated` | Added to new pages and substantive edits; optional on imports | When its content last changed |

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:

| File under `$ENSO_HOME/skills/enso-knowledge/` | Purpose |
| --- | --- |
| `SKILL.md` | Where knowledge goes and how the agent reads, writes, links, and checks it |
| `references/formatting.md` | The common writing and formatting rules |
| `scripts/lint.py` | A read-only checker for the mechanical style rules |

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:

```bash
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:

```bash
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:

```bash
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](/docs/cli/#knowledge)
lists the commands for scripts and direct use:

```bash
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.