> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monolex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Monomento

> Memory document search — trigram search + reference graph traversal for .md/.mdx/.aiin files.

Monomento indexes markdown documents into SQLite, enabling fuzzy search by topic and reference graph navigation. It stores full document content — no filesystem access needed after indexing.

*Published contract: `monomento 0.3.2`, OpenCLIs build
`2026-07-18-132645`, source commit
`2d9f808e9cb24c7b37f065b523bc76426f27f7fb`. The executing binary, registry,
and public CDN metadata agree on this clean successor to the incomplete 0.3.1
publication.*

The installed surface has **13 operational command families**, one canonical
alias (`path` for `path-search`), plus `docs`, `help`, and `version`. Monomento
does not expose a direct MCP server: higher layers such as MonoBrain, MonoFlow,
and Work Wiki compose its library and database contracts.

The public OpenCLIs `initiate_md` now contains the exact 0.3.2 packaged guide:
20,084 bytes with SHA-256
`293215f99f961e4959708872063fdf9e42e591cadf68da2e99ae5fa0458f7dfd`.
It intentionally documents the released 13-family surface, not a source-ahead
command that the installed binary cannot execute.

<Card title="Bring sources into memory" icon="download" href="https://monolex.ai/tools/ingest/">
  Choose how to fetch and convert web pages, documents, feeds, or Wikipedia before indexing them with Monomento.
</Card>

***

## Quick Start

```bash theme={null}
# Install the current public payload
openclis install monomento
openclis update monomento

# Index a documentation directory
monomento index ~/docs --project

# Search by topic
monomento search "trigram search"

# Follow reference graph
monomento tree SKILL.md --depth 2

# Read document structure
monomento peek LLM-BEHAVIORAL-PATTERNS.md

# Read full content from DB
monomento read 08-smpc-defined.md
```

***

## Memory Access Flow

```
┌──────────────────────────────────────────────────────────────────┐
│  MEMORY ACCESS FLOW                                              │
├──────────────────────────────────────────────────────────────────┤
│                                                                  │
│  1. SEARCH  →  Find documents by topic (fuzzy trigram)           │
│  2. TREE    →  Follow reference graph, narrow the path           │
│  3. PEEK    →  Read document structure + content previews        │
│  4. READ    →  Retrieve full content from DB                     │
│                                                                  │
│  Each result guides your next move.                              │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘
```

***

## Commands

| Command                                | What it does                                                                                                                                           | Read/write boundary                                             |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------- |
| `search <query>`                       | Ranks document/section content with the v11 IDF + word coverage score.                                                                                 | Read-only.                                                      |
| `path-search <query>` / `path`         | Searches the separate indexed-path trigram plane.                                                                                                      | Read-only; paths do not distort topic relevance.                |
| `tree <document>`                      | Renders a hierarchical DFS reference graph.                                                                                                            | Read-only.                                                      |
| `chain <document>`                     | Renders a flat BFS reference chain by depth.                                                                                                           | Read-only.                                                      |
| `peek <document>`                      | Shows all headings, previews, line ranges, and ref counts.                                                                                             | Read-only.                                                      |
| `read <document...>`                   | Returns stored original content or selected heading levels/sections.                                                                                   | Read-only; does not need the source file after indexing.        |
| `bridge <document...>`                 | Finds content-similar documents or compares an exact pair using trigram Jaccard.                                                                       | Read-only.                                                      |
| `spread <document...>`                 | Runs multi-seed spreading activation over the reference graph.                                                                                         | Read-only; optional content similarity contribution.            |
| `resonate <query>`                     | Searches lexical seeds, spreads activation, and merges the scores.                                                                                     | Read-only composed recall.                                      |
| `deps <document>` / `rdeps <document>` | Lists outgoing or incoming references.                                                                                                                 | Read-only.                                                      |
| `index <path>`                         | Creates/migrates and writes document, heading, trigram, path, and reference state; `--project --adopt` can register an existing corpus without a walk. | Writer command; only this surface initializes or migrates a DB. |
| `stats`                                | Reports global or project database statistics.                                                                                                         | Read-only.                                                      |
| `docs [topic]`                         | Lists or prints embedded reference topics.                                                                                                             | The public build currently ships the `index` topic.             |
| `help` / `--help` / `-h`               | Prints the complete installed guide.                                                                                                                   | Read-only.                                                      |
| `version` / `--version` / `-V`         | Prints the executing version.                                                                                                                          | Read-only.                                                      |

### Source-ahead `ingest-trajectory`

Current repository source at commit
`73ded8644ea2749b5513a1b0061d8bcf8c44cce0` adds a 14th family:

```bash theme={null}
monomento ingest-trajectory <root> --out <corpus-dir>
```

It projects LongMemEval-V2-shaped
`<root>/<trajectory-id>/trajectory.json` data into one Markdown document per
state, using filenames such as `state__t_<id>__s<NNNN>.md`. The filename and
frontmatter carry `state_index` as the span coordinate; the original step is
metadata only. Each document uses the goal as H1 and Action, URL, and AXTree as
H2 sections. Unchanged projected files are not rewritten, so a repeated run is
idempotent at the file layer.

By default the command indexes the projected corpus after writing it.
`--no-index` performs projection only; `--db`, `--project`, `--adopt`, `--gc`,
and `--gc-dry-run` are forwarded to the index step. The source guide has SHA-256
`432b7d95a32dc03a26e8506818d706b2d492553311a55e0d15f2fcb8478a0d6b`.
The public 0.3.2 payload responds `Unknown command: ingest-trajectory`, so this
section is source-head documentation, not an instruction to use the command on
the current release.

Every retrieval family accepts `--project` to select the deepest registered
ancestor of the current directory. Without it, the command reads the global
database. `--db <path>` is an `index`-only ownership override; it is not a
general reader flag.

### search

Find documents matching a topic using trigram fuzzy matching.

```bash theme={null}
monomento search <query> [-n limit] [--read] [--h2] [--h2+] [--explain]
```

| Flag         | Description                                            |
| ------------ | ------------------------------------------------------ |
| `-n <limit>` | Max results (default: 20)                              |
| `--read`     | Show full section content inline                       |
| `--h2`       | Filter sections by exact heading level                 |
| `--h2+`      | Filter by level range (h2 and deeper)                  |
| `--explain`  | Show score component breakdown                         |
| `--basic`    | Use legacy basic trigram scoring explicitly            |
| `--idf`      | Use the IDF-weighted variant without word-match tuning |

Default search uses coverage × IDF with heading, body, H1, H2, and filename
boosts. There are no boolean operators: `AND`, `OR`, quotes, `+term`, and
`-term` are literal input. Prefer two or more distinctive words to reduce
shared-trigram leakage.

### path-search / path

Search canonical indexed paths rather than document content.

```bash theme={null}
monomento path-search "github monolex" --contains '.claude/projects'
monomento path "session gateway" --type brain -n 20
```

`--contains` is repeatable, and `--type` filters the indexed document type.
This command uses a separate path index so URL/filesystem strings cannot inflate
content-search scores. The installed parser accepts `-n`; it does not expose a
`--limit` spelling for this command.

### tree / chain

Follow reference graphs (DFS tree or BFS chain).

```bash theme={null}
monomento tree <document> [--forward|--backward] [--depth N]
monomento chain <document> [--forward|--backward] [--depth N]
```

`tree` also accepts `--max-children N` (default 20) and `--full`. The latter
expands repeated paths instead of deduplicating them. `chain` is the flat BFS
view; `tree` is the hierarchical DFS view.

### peek

Read full document structure with content previews.

```bash theme={null}
monomento peek <document>
```

### read

Retrieve full content from database (no filesystem needed).

```bash theme={null}
monomento read <document> ["Section Name"] [--h2] [--h2+]
monomento read <doc1> <doc2> --h2             # Multi-doc read
monomento read <doc1> <doc2> --h2 "filter"    # Multi-doc + name filter
```

Heading selectors cover `--h1` through `--h6`; append `+` to include that
level and all deeper levels (`--h2+`, for example). With multiple documents,
a trailing non-flag string is the section-name filter.

### bridge

Find content-similar documents (Jaccard similarity on trigrams).

```bash theme={null}
monomento bridge <document> [-n limit] [--cross]
monomento bridge <doc1> <doc2>                 # Pairwise comparison
```

### spread / resonate

```bash theme={null}
monomento spread architecture.mdx security.mdx --depth 2 --lambda 0.5
monomento resonate "session gateway auth" --seeds 5 --content --expand
```

`spread` starts from one or more exact documents and propagates activation over
references; `--content` adds Jaccard similarity. `resonate` discovers lexical
seeds first, then spreads and merges them. Both accept depth/decay controls;
`resonate --expand` adds pseudo-relevance feedback.

### deps / rdeps

```bash theme={null}
monomento deps <document>     # What does this document reference?
monomento rdeps <document>    # Who references this document?
```

### index / stats

```bash theme={null}
monomento index <path> [--ext md,mdx,txt,aiin] [--project]
monomento index <path> --project --adopt
monomento index <path> --db /absolute/cache.db
monomento index <path> --gc-dry-run
monomento index <path> --gc
monomento index <path> --retry-failed
monomento index <path> --files-from changed-paths.txt
monomento stats [--project]
```

A successful full directory `--project` index registers one canonical root and
its extension/exclusion policy for NIIA watcher dirty passes. `--files-from`
applies exact newline-separated files or directory witnesses atomically under a
previously stamped project or explicit DB; it never creates registration.
Existing paths refresh eligible descendants, while missing paths purge their
exact keys and descendants.

`--adopt` is a fail-closed bootstrap for a legacy project corpus whose
deterministic project DB already exists. It writes the extension policy with
`registration_catchup_pending=1`, increments the generation, registers the
canonical root, and returns without a directory walk. The NIIA dirty driver
then drains the catch-up in batches; use the printed
`niia index --dirty --dirty-project <root>` next step to drain immediately.
It requires `--project`, rejects `--db`, `--files-from`, GC, and retry options,
and never creates a first corpus. A fresh project must complete one full
`monomento index <root> --project` publication.

`--gc-dry-run` previews stale-row removal. `--gc` applies it, and a subdirectory
walk never removes rows owned by other roots. `--retry-failed` clears unreadable
file markers before retrying. Full and incremental writers share a per-project
lock; readers fail closed while a registration catch-up generation is pending.

## Storage and Freshness

| Scope   | Database                                |
| ------- | --------------------------------------- |
| Global  | `~/.monolex/monomento.db`               |
| Project | `~/.monolex/monomento/<name>-<hash>.db` |

Project readers choose the deepest registered ancestor of the current
directory. A tombstoned, unreadable, or missing registered DB does not silently
fall back to a deterministic path. Filesystem skip checks use nanosecond mtime
fingerprints, while the public `modified_at` field remains Unix epoch seconds.

## Release Platforms

The `0.3.2` build publishes six platform artifacts. `latest.json` and every
platform row pin source commit
`2d9f808e9cb24c7b37f065b523bc76426f27f7fb` with `source_dirty: false`; this
is the complete clean successor to the partial 0.3.1 publication. Archive
hashes were re-read from CDN metadata and independently recomputed. Payload
hashes are over the extracted executable, not the surrounding archive.

| Platform key      | Binary          | Archive SHA-256                                                    | Payload SHA-256                                                    | Direct proof                                                                                       |
| ----------------- | --------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
| `darwin-aarch64`  | `monomento`     | `93ccef40eb0c417975e4f02f695dc54d4aee970042d0a8bb5ce792c484a51551` | `69eca8e0324b2df2ccb06fe6fd4cf90de088c7b6513c75aa68ab677c45603272` | Strict Developer ID verification, accepted notarization, installed and executed on Apple Silicon   |
| `darwin-x86_64`   | `monomento`     | `a233cbfd9a22c786235a75a2b295f5ae3ff6c246e90d0c30b41030f7661fdb6b` | `c6565c7e779d3b5fa025d1163f3cc794e039e9830e2ed7fc875bc83f0302e37b` | Strict Developer ID verification and Rosetta execution on Apple Silicon                            |
| `linux-aarch64`   | `monomento`     | `03cd6e1e9675c10f1c1a6ceeb391e7759ce11847f68b1f1e021af03a73bfd428` | `a97a966c1efc3af61fa8066ba99a55dce3f09a626386d1e909d34c5ff93122b3` | AArch64 GNU/Linux ELF and packaged guides inspected; not claimed as a native runtime smoke         |
| `linux-x86_64`    | `monomento`     | `ad9f1465e2c8b996d63b0ea37798158d53231674420d0279fd2c8bba1eb4e42d` | `f69650a60884242fd01bc8fcd023bc08a40bebf6b655c5f5a9c5a7310470fa0a` | Installed and executed in Ubuntu 24.04 WSL; packaged guides equal release source                   |
| `windows-aarch64` | `monomento.exe` | `91d20fc807d140870f6b509b5f13c0ecb4f231231aaa8c82d504b0ffff52d677` | `c7ef3d93639dac4f589a9274b1e06c2629cd11bf629b4ca021d72908bafafd6d` | AArch64 PE and packaged guides inspected; not claimed as a native runtime smoke                    |
| `windows-x86_64`  | `monomento.exe` | `73621bd5a16ba882acb61892c632aa50a10e2c7d14de8f856ea1c18c9b32b134` | `420e6df38c0355c79c1f8e1953463606f7f05d09801f0936c4c871fb7e4d20a4` | Installed and executed on Windows 11, including an isolated full-index then no-walk adoption smoke |

Every archive also carries `initiate.md`, `SKILL.md`, `initiate.json`, and the
deep `docs/index.md` topic. Their content matches the pinned 0.3.2 release
source; the Windows x86-64 checkout differs only by CRLF line endings. The
packaged and installed guide therefore remains the 13-family hash
`293215f99f961e4959708872063fdf9e42e591cadf68da2e99ae5fa0458f7dfd`,
while the current repository guide is the separate source-ahead hash shown
above.

***

## Document Types

| Extension | Description                            |
| --------- | -------------------------------------- |
| `.md`     | Markdown documents                     |
| `.mdx`    | MDX documents (Markdown + JSX)         |
| `.aiin`   | AIIN fragments (consciousness anchors) |
| `.txt`    | Plain text documents                   |

All types are parsed for headings, links, mentions, anchors, and trigram content.

## Relationships

| Tool                                  | Ownership                                                                              |
| ------------------------------------- | -------------------------------------------------------------------------------------- |
| [MonoFetch](/ai-clis/monofetch)       | Fetches web pages and can hand converted Markdown to Monomento                         |
| [MonoAPI](/ai-clis/monoapi)           | Converts OpenAPI/Swagger specifications before indexing                                |
| [MonoRSS](/ai-clis/monorss)           | Converts feed entries before indexing                                                  |
| [MonoWiki](/ai-clis/monowiki)         | Converts Wikipedia articles before indexing                                            |
| [NIIA](/ai-clis/niia)                 | Exposes Monomento-backed document commands and owns the dirty-driver catch-up workflow |
| [MonoFlow](/ai-clis/monoflow)         | Composes Monomento documents with code, Git, and work evidence                         |
| [Work Wiki](/ai-clis/work-wiki)       | Reads Monomento as the knowledge layer in project-wide work search and convergence     |
| [MonoBrain](/ai-clis/monobrain)       | Synthesizes instructions and memory from indexed document evidence                     |
| [NIIA Watcher](/ai-clis/niia-watcher) | Delivers registered project changes through exact `--files-from` dirty passes          |