Knowledge and logs

makermap has two places to write things down, and the difference between them is not a category - it is how they are written.

Documents are rewritten whole

A document is markdown, addressed by a slug within a product. You edit it and it is saved as a new revision; the whole body is snapshotted, so you can read any past version and see what changed. Good for anything that has a current state: a spec, a brief, an onboarding note.

Every product can own a document called agent-handoff, and that name is a convention the product knows: it is included in the product's context package, so an agent picking up a session reads it without being told to.

Logs are appended one entry at a time

A log is a named, append-only stream, read from the tail. Ask for the last three entries and you get three entries, not a file you have to scroll. Good for anything that accumulates: a changelog, a decision journal, a running record of what a long job did.

An entry is never edited and never deleted, in any transport. A correction is a new entry that supersedes the old one, so the record of having been wrong survives. Threads are not a log feature - per-element comments are for that.

Why they are not one thing with a type field

It looks like a document just needs type: 'log'. It does not, and the reason is arithmetic. A document revision snapshots the entire body, so appending n entries to one costs n(n+1)/2 times the body - the 44th entry appended to a 106 KB changelog would copy the 43 before it. Two write modes that different deserve two entities.

Searching them

search finds things by keyword across every entity. It also has a semantic mode, which embeds your query and matches on meaning rather than words, and follows one hop through the links between records. Semantic search is the one operation in the product that runs a model, which is why it is the one operation that costs credits.