Skip to main content
Almanac saves maintained knowledge and ongoing work as records in your personal account. A record has a stable ID, a canonical path, a revision, structured fields and, where useful, a Markdown body. The CLI reads and edits these records over HTTP; a local file used as command input is not a second copy of the wiki.

​
Choose the record that represents the thing

The knowledge kinds are person, organisation, place, event, creative_work, topic and page. A person can carry roles and relationships; an organisation can be referenced from those roles. A topic is an article about a subject, not a required folder for every page. An event record is maintained knowledge about an event, distinct from a calendar occurrence. A page is ordinary authored knowledge, not a copied email thread.
Use the schema for required descriptions, exact field names and typed reference shapes before creating or changing a record. A reference identifies an existing record with both its kind and ID, for example {"type":"organisation","id":"33333333-3333-4333-8333-333333333333"}. This ID is fictional; use an ID returned by your own read or search. A name in prose does not establish a structured relationship. Tasks and projects are records too, but they describe work rather than knowledge about a subject. A task can belong to a project and has one primary session. A session is the conversation history and may exist without a task; tracking a session attaches task metadata to that same conversation. Assigning a task to a project changes the task’s project reference; mentioning the project in its body does not. Tasks and projects explains their states and updates.

​
Paths, revisions and relationships

Use the returned ID or canonical path to read a record. Paths such as people/sam-fictional are addresses, not filesystem locations. The ID remains useful when titles or paths change. A full read includes the revision needed for a guarded edit; read --body returns only Markdown and is insufficient on its own for an update.
Links can come from structured references, mentions in body text and citations. Incoming links are the default. Follow the returned kind and target rather than treating every link as an editable wiki page: a citation points to a source, while a task’s session points to a conversation. Search and read covers result shapes and navigation; editing knowledge covers revisioned changes.