Motivation
Basic Memory should have a documentation set written in the style of Unix man pages, but implemented as Basic Memory notes.
This is related to #610, which focuses on shipping traditional man pages for bm CLI commands. This issue is broader: create a manual or manpages Basic Memory project/folder that documents commands, file formats, concepts, schemas, and advanced memory patterns using man-page structure and Basic Memory graph links.
The product idea fits the Unix/Git framing:
- Unix man pages are compact, structured, durable documentation.
- Git became powerful by introducing new nouns and verbs.
- Basic Memory is developing its own nouns and verbs: notes, observations, relations, schemas, activity, versions, materialized views, and memory routines.
- If Basic Memory docs are also Basic Memory notes, the documentation becomes searchable, linkable, semantically indexed, and useful to both humans and agents.
Proposal
Create a Basic Memory manual page documentation set.
Example note frontmatter:
title: bm-write(1)
type: manpage
section: 1
name: bm-write
summary: write or update a Basic Memory note
tags: [manual, cli, notes]
Example body:
# bm-write(1)
## NAME
bm-write - write or update a Basic Memory note
## SYNOPSIS
bm write [PROJECT] [TITLE] [OPTIONS]
## DESCRIPTION
Creates or updates a markdown note, parses semantic observations, extracts wikilinks, and updates the knowledge graph.
## OPTIONS
--type
--tags
--folder
--overwrite
## EXAMPLES
bm write "Decision - Use Postgres"
## SEE ALSO
[[bm-search(1)]], [[bm-read(1)]], [[bm-schema(5)]], [[bm-routine(5)]]
Manual Sections
Use traditional Unix-style section numbers adapted for Basic Memory:
1 - Commands: bm(1), bm-search(1), bm-read(1), bm-write(1), bm-sync(1), bm-cloud(1)
3 - APIs / MCP tools: search-notes(3), read-note(3), write-note(3), build-context(3)
5 - File formats / schemas: bm-note(5), bm-observation(5), bm-relation(5), bm-schema(5), bm-routine(5)
7 - Concepts: basic-memory(7), semantic-memory(7), episodic-memory(7), procedural-memory(7), activity-feed(7), materialized-view(7)
8 - Admin / cloud operations: cloud setup, project sync, hosted runtime, enterprise/on-prem notes later
Why as Basic Memory notes?
Because the manual becomes a knowledge graph:
SEE ALSO links become relations.
- Concept pages can link to command/API pages.
- Agents can search and build context from the docs directly.
- Docs can evolve with observations like
[gotcha], [example], [decision], and [pattern].
- Schema-backed
manpage notes can validate consistency across the manual set.
- The manual can be exported later to real man pages, website docs, MCP prompts, or bundled skills.
Initial Scope
Start with a small seed set:
bm(1) - overview and command family
bm-search(1) - search examples and flags
bm-read(1) - reading notes and memory URLs
bm-write(1) - writing notes with observations and relations
bm-note(5) - semantic markdown note format
bm-observation(5) - observation syntax and categories
bm-relation(5) - relation syntax and graph edges
basic-memory(7) - the conceptual overview
semantic-memory(7) - notes, entities, observations, relations, schemas
episodic-memory(7) - activity, versions, timelines, project updates
procedural-memory(7) - routines, skills, workflows, materialized views
Acceptance Criteria
Open Questions
- Should the manual live in the
specs project, a dedicated manual project, or under docs in the main Basic Memory knowledge base?
- Should
bm man <topic> search/read these notes locally?
- Should manual pages be generated from docs, or should docs be generated from manual-page notes?
- Should MCP prompts expose the same content as agent-friendly command references?
- Should the hosted docs site render these notes as browsable man pages?
Motivation
Basic Memory should have a documentation set written in the style of Unix man pages, but implemented as Basic Memory notes.
This is related to #610, which focuses on shipping traditional man pages for
bmCLI commands. This issue is broader: create amanualormanpagesBasic Memory project/folder that documents commands, file formats, concepts, schemas, and advanced memory patterns using man-page structure and Basic Memory graph links.The product idea fits the Unix/Git framing:
Proposal
Create a Basic Memory manual page documentation set.
Example note frontmatter:
Example body:
Manual Sections
Use traditional Unix-style section numbers adapted for Basic Memory:
1- Commands:bm(1),bm-search(1),bm-read(1),bm-write(1),bm-sync(1),bm-cloud(1)3- APIs / MCP tools:search-notes(3),read-note(3),write-note(3),build-context(3)5- File formats / schemas:bm-note(5),bm-observation(5),bm-relation(5),bm-schema(5),bm-routine(5)7- Concepts:basic-memory(7),semantic-memory(7),episodic-memory(7),procedural-memory(7),activity-feed(7),materialized-view(7)8- Admin / cloud operations: cloud setup, project sync, hosted runtime, enterprise/on-prem notes laterWhy as Basic Memory notes?
Because the manual becomes a knowledge graph:
SEE ALSOlinks become relations.[gotcha],[example],[decision], and[pattern].manpagenotes can validate consistency across the manual set.Initial Scope
Start with a small seed set:
bm(1)- overview and command familybm-search(1)- search examples and flagsbm-read(1)- reading notes and memory URLsbm-write(1)- writing notes with observations and relationsbm-note(5)- semantic markdown note formatbm-observation(5)- observation syntax and categoriesbm-relation(5)- relation syntax and graph edgesbasic-memory(7)- the conceptual overviewsemantic-memory(7)- notes, entities, observations, relations, schemasepisodic-memory(7)- activity, versions, timelines, project updatesprocedural-memory(7)- routines, skills, workflows, materialized viewsAcceptance Criteria
manpagenote schema.SEE ALSOwikilinks so the manual forms a graph.Open Questions
specsproject, a dedicatedmanualproject, or under docs in the main Basic Memory knowledge base?bm man <topic>search/read these notes locally?