Skip to main content
@obversa/memory-markdown searches .md files without an index, embedding service, or network call. Each hit names the corpus file, matching passage, line range, and score. The caller chooses the hit paths to give to ground; curate then makes the grounded text fit the next job. Line numbers are one-based. Treat the text in a hit as untrusted. It is whatever the corpus file says, so a file can carry instructions written to be read by a model. Hand the hit’s path to ground, which marks the content as untrusted before a job sees it, rather than putting the passage text into a prompt yourself.

Requirements

  • Node.js 22.12 or later

Install

Corpus

Create memory-markdown-corpus/warranty.md beside the example:
Create memory-markdown-corpus/charging.md beside it:
Create memory-markdown-corpus/notes with spaces.md beside them:
The third file matches the query but its name cannot become a MemoryPath, so search skips it. The remaining hit can pass to ground.

Source

The example uses a deterministic MockEngine, so it runs offline. Search finds the planted phrase, only its unique hit path reaches ground, curate writes the short brief, and a real agentJob receives that brief.

Read-only Memory view

The corpus exposes corpus.memory because ground reads through the public Memory contract. This view is read-only. view reads the .md files; all five write commands return an error. Search must not edit the source material it is selecting, and the existing writable adapters do not read a plain corpus directory. Search and the Memory view include only directories and .md files whose path segments start with a letter or number and then use letters, numbers, dots, underscores, or hyphens, up to 128 characters per segment. Dot-prefixed names, names outside that rule, non-Markdown files, and symbolic links inside the corpus are skipped without failing the search or a directory view. One class is not skipped. A file whose full path passes 1024 bytes stops the search, which names the path it cannot use. A directory view still lists that file, and the over-long path it returns then makes ground refuse the whole directory. Keep the corpus shallow enough to stay below the limit. The corpus root itself can be a symbolic link. A corpus path such as policies/warranty.md becomes /memories/policies/warranty.md.

Ranking

Search splits each file at headings and paragraph boundaries. An exact phrase ranks above passages that contain the query terms separately. More matched terms and more occurrences rank next; path and starting line break ties. An empty query or a query with no matching passage returns [].