Entities, facts, ontology

This page covers the derived layer, so it assumes you have read Sources and derived knowledge. It also owns the source tag syntax, so every other mention of tags and declarations links back here.

Named things and statements about them

Reading a note, aizk pulls out two kinds of thing.

An entity is a named thing the note talks about, like a person, a project, a paper, a tool, or a method. The web app calls these Subjects.

A fact is one statement linking named things, kept next to the sentence it came from. The web app calls these Findings. A fact has a subject, a predicate, and usually an object, and that shape is what lets you traverse it rather than only read it.

Every edge there came out of somebody’s prose, and every edge still remembers the quote it came from.

Where this comes from

Treating memory as a temporal graph of entities and the facts that link them follows Zep and Graphiti. The references map traces every borrowed idea back to its source.

The vocabulary is a live catalog

aizk does not accept arbitrary types. Entity kinds and relation predicates come from a catalog in the database, and a deployment can extend it without touching code.

The catalog ships seeded across a few families. General work has kinds like Project, Area, Status, Tool, Person, Decision and Goal. Research adds Paper, Method, Model, Dataset, Metric, Experiment and more, and there are coding, finance and personal families too. Predicates arrive the same way, among them part_of, has_status, depends_on, supersedes, uses, proves and cites.

Two things follow. Anything the engine reads from your prose lands on a kind that really exists, or on the generic Concept when nothing fits, rather than inventing a type. And when you declare a type yourself, the name has to be in the catalog or the write is rejected with a message naming the unknown kind.

Declaring things yourself

The engine reads a plain note and does a decent job. Declaring is how you get an exact result instead of a decent one, and it costs three lines.

A declaration is a compact block right after the note’s level-one heading. Three line shapes are recognized, and the first line that is none of them ends the block, so ordinary prose below stays safe from being read as metadata.

#<kind>: <name> associates the note with something

# Upload security decision

#project: aizk
#area: Business

Each tag connects the note’s title to a typed entity through the generic related_to predicate. A tag says “this note belongs in that neighborhood” and nothing more. It never implies status, ownership, access, or write scope. Tagging a note #project: aizk does not put it in that project’s scope and does not mark the project active.

A tag whose name matches the level-one heading is special. It declares the heading itself to be that kind, so a note titled aizk tagged #project: aizk becomes the Project entity rather than merely relating to it.

- Type <kind> declares what the note is about

# aizk

- Type Project

This is the explicit form of the same-name trick, and it is the clearer one. The kind must exist in the live catalog, and the heading supplies the entity’s name.

- <predicate> [<object kind>] <object name> states a relation

# aizk

- Type Project
- part_of [Area] Business
- has_status [Status] Active
- uses [Method] GLiNER2

The predicate and the object kind both have to be in the catalog. A relation line only takes effect once the note has declared its own type, because a relation needs a subject to hang from.

Nothing here is mandatory. A note with no declarations is stored as an ordinary note and the engine reads what it can. A note with a type and no relations leaves those connections as honest gaps rather than guesses.

Perspective, or who a statement belongs to

Not every statement is about the world. Some are about a person.

“The Leech lattice reaches the best known packing in 24 dimensions” is world knowledge. It is true or false no matter who says it, so two people asserting it are asserting one thing.

“I prefer the smaller model because the latency is easier to live with” is not. It is a preference, and it belongs to whoever said it. So does an observation somebody made or an opinion somebody holds.

aizk keeps that distinction on every fact. A statement is either world knowledge or bound to a speaker, and speaker-bound statements are kept apart per person rather than merged. So two teammates can hold opposite preferences without looking like a contradiction, while two teammates asserting different world facts genuinely do conflict and get treated that way.

Facts also carry the shape of the claim, whether it is a procedure, a negative result, an observation, and so on. A negative result is worth as much as a positive one and is kept as deliberately.

When the graph earns its keep

Plain search is fine when you know the words you are looking for. The graph handles the questions where you do not.

Asking what a project depends on, what a decision replaced, or which papers used a method means walking edges rather than matching strings. Recall does exactly that behind the scenes, starting from the things your question mentions and pulling in what sits one or two steps away. That is why a well declared note pays back later, and why the effort belongs at write time.

Next

• Writing memory well puts the tag syntax to work on real notes.
• Notes that stay useful covers the writing habits that build good graphs.
• Evidence and provenance shows how facts come back at recall time.