From 6f3322f1bafc07c11312c5b762a6e8b611199077 Mon Sep 17 00:00:00 2001 From: Andy Dixon Date: Wed, 8 Jul 2026 21:42:40 +0100 Subject: [PATCH] docs site: landing page, htaccess in the build output --- docs/site/build.py | 12 +++++- docs/site/htaccess | 18 +++++++++ docs/site/pages/index.md | 82 ++++++++++++++++++++++++++++++---------- 3 files changed, 91 insertions(+), 21 deletions(-) create mode 100644 docs/site/htaccess diff --git a/docs/site/build.py b/docs/site/build.py index 247e900..568fe05 100644 --- a/docs/site/build.py +++ b/docs/site/build.py @@ -25,7 +25,7 @@ SITE = "https://dixon.cx" # Order, slug, title, summary. The page body comes from pages/.md. CHAPTERS = [ - ("index", "Overview", "What Noema is, what it refuses to claim, and how the pieces fit."), + ("index", "Noema", "A persistent, inspectable artificial cognitive runtime: minds that remember, reason with evidence, say how sure they are, and can always show their working."), ("concepts", "Concepts and vocabulary", "Minds, events, epistemic kinds, memory kinds, beliefs, drives and the interpretation boundary."), ("architecture", "Architecture", "The daemon, the cognitive cycle, the storage model and the boundaries between deterministic code and language models."), ("getting-started", "Getting started", "From an empty machine to a running mind you can talk to, inspect and replay."), @@ -73,6 +73,13 @@ STYLE = """ .noema-doc dl dt{font-weight:600;margin-top:.6rem}.noema-doc dl dd{margin-left:0} .noema-doc .section-box p+p,.noema-doc .section-box p+ul,.noema-doc .section-box p+ol,.noema-doc .section-box ul+p,.noema-doc .section-box ol+p,.noema-doc .section-box .table-wrap+p,.noema-doc .section-box pre+p{margin-top:.9rem} .noema-doc .lead-ish{font-weight:600;opacity:.9;margin-bottom:1rem} +.noema-doc .hero{margin:.5rem 0 0}.noema-doc .hero-kicker{font-family:monospace;letter-spacing:.08em;text-transform:uppercase;font-size:.78rem;opacity:.7;margin:0 0 .4rem} +.noema-doc .hero-lead{font-size:1.15rem;line-height:1.55;margin:0 0 1rem}.noema-doc .hero-actions{display:flex;flex-wrap:wrap;gap:.5rem;margin:0} +.noema-doc .pillars{display:grid;grid-template-columns:repeat(2,1fr);gap:1rem}@media(max-width:760px){.noema-doc .pillars{grid-template-columns:1fr}} +.noema-doc .pillar{border:1px solid rgba(127,127,127,.3);border-radius:8px;padding:1rem 1.1rem}.noema-doc .pillar h3{margin:0 0 .5rem;font-size:1rem}.noema-doc .pillar p{margin:0;font-size:.95rem} +.noema-doc .shots{display:grid;grid-template-columns:repeat(2,1fr);gap:1rem}@media(max-width:760px){.noema-doc .shots{grid-template-columns:1fr}}.noema-doc .shots figure{margin:0} +.noema-doc .numbers{display:grid;grid-template-columns:repeat(3,1fr);gap:1rem;text-align:center}@media(max-width:760px){.noema-doc .numbers{grid-template-columns:repeat(2,1fr)}} +.noema-doc .numbers div{border:1px solid rgba(127,127,127,.3);border-radius:8px;padding:1rem .6rem}.noema-doc .numbers b{display:block;font-size:1.9rem;line-height:1.1}.noema-doc .numbers span{display:block;font-size:.82rem;opacity:.8;margin-top:.3rem} """ @@ -298,7 +305,7 @@ def openapi_markdown(): def render_page(idx, slug, title, summary, md): md = expand(md) - conv = markdown.Markdown(extensions=["tables", "fenced_code", "toc", "sane_lists", "attr_list", "def_list"], extension_configs={"toc": {"toc_depth": "2-3"}}) + conv = markdown.Markdown(extensions=["tables", "fenced_code", "toc", "sane_lists", "attr_list", "def_list", "md_in_html"], extension_configs={"toc": {"toc_depth": "2-3"}}) body = conv.convert(md) body = rewrite_links(body) body = re.sub(r"", '
', body).replace("
", "") @@ -350,6 +357,7 @@ def main(): if f.endswith(".png"): shutil.copy(os.path.join(ROOT, "docs", "screenshots", f), os.path.join(out, "img", f)) shutil.copy(os.path.join(ROOT, "internal", "api", "openapi.json"), os.path.join(out, "openapi.json")) + shutil.copy(os.path.join(ROOT, "docs", "site", "htaccess"), os.path.join(out, ".htaccess")) for i, (slug, title, summary) in enumerate(CHAPTERS): with open(os.path.join(PAGES, slug + ".md"), encoding="utf-8") as f: md = f.read() diff --git a/docs/site/htaccess b/docs/site/htaccess new file mode 100644 index 0000000..66d708f --- /dev/null +++ b/docs/site/htaccess @@ -0,0 +1,18 @@ +DirectoryIndex index.html + + +RewriteEngine On +RewriteBase /noema/ + +# One canonical URL per page: the index at the directory, pages without an +# extension. The .html and trailing-slash forms redirect. +RewriteRule ^index\.html$ /noema/ [R=301,L] +RewriteCond %{THE_REQUEST} \s/+noema/([a-z0-9-]+)\.html(?:[?\s]|$) [NC] +RewriteRule ^([a-z0-9-]+)\.html$ /noema/$1 [R=301,L] +RewriteRule ^([a-z0-9-]+)/$ /noema/$1 [R=301,L] + +# Serve pages from their .html files. +RewriteCond %{REQUEST_FILENAME} !-f +RewriteCond %{REQUEST_FILENAME}.html -f +RewriteRule ^([a-z0-9-]+)$ $1.html [L] + diff --git a/docs/site/pages/index.md b/docs/site/pages/index.md index bcb170b..65da589 100644 --- a/docs/site/pages/index.md +++ b/docs/site/pages/index.md @@ -1,31 +1,75 @@ -Noema is a persistent, inspectable artificial cognitive runtime. It is a daemon, written in Go and backed by PostgreSQL, that hosts one or more *minds*: long-lived cognitive entities with their own identity, personality, memories, beliefs, goals, drives, affective state and an append-only history of everything they have ever thought. This documentation describes what Noema is, how it is built, how to run it, and how to read what it does. +
+

An artificial cognitive runtime

+

Most AI systems answer. Noema thinks, remembers, doubts and can show its working. It is a persistent runtime that hosts minds: long-lived cognitive entities with their own identity, memories, beliefs with evidence, goals, drives and an unbroken record of every thought they have ever had. Language models are plug-in services it calls when it needs language. The mind is the thing that stays.

+

Run it in ten minutes See every screen Read the architecture

+
-## What Noema is +## Why it is different -A mind in Noema is not a chat session. It runs continuously whether or not anyone is talking to it. Events arrive from many sources: a message from an operator, a file dropped in a watched folder, a commit in a mirrored repository, a metric crossing a threshold, a signed webhook, or the mind's own background processes. Each event is recorded, perceived, and offered to a set of cognitive processes that compete for a small, capacity-limited **workspace**. Whatever wins that competition is what the mind is "thinking about", and the executive layer acts on it: encoding memories, forming or revising beliefs, updating goals, making predictions, and, only through a policy-governed capability layer, doing things in the world. +
+

It never loses the thread

A mind runs whether or not anyone is talking to it. Messages, documents, commits, metrics and webhooks arrive as events; the mind perceives them, recalls what is relevant, forms and revises beliefs, and picks up exactly where it left off after a restart. There is no context window to fall off the end of.

+

Confidence is earned, not asserted

Every proposition says what kind of knowledge it is. A claim stays a claim until independent evidence arrives, confidence is computed by a formula you can read on the page, and one source repeating itself is discounted. A Noema mind says I do not know because the arithmetic tells it to.

+

You can always ask why

Every thought that reached the workspace carries its attention score and its parents. Every memory carries its source and trust. Every reply carries the beliefs it rests on. Every model call is recorded with its prompt version. Nothing in the history can be edited, by anyone, including the mind.

+

It cannot act behind your back

The only path to the outside world is a capability layer with ALLOW, ASK and DENY policies, approvals bound to the exact request, and two capabilities locked shut forever. Dreams and replays cannot act at all. There is no self-preservation drive; shutdown is always yours.

+

The model is replaceable

Perception, hypothesis, summary, judgement, narrative and response are roles. Point a role at OpenAI, Anthropic, a local Ollama or nothing at all: the deterministic core keeps working, the mind keeps its identity, memories and beliefs, and recorded calls make model-dependent steps reproducible.

+

Built to be studied

Snapshot a mind, fork it, change one thing, and compare. Replay its recorded cognition and see, step by step, whether the result was exact, approximate or diverged. Run controlled experiments with stimulus scripts and expectations. This is a laboratory, not a chatbot.

+
-The result is a system you can ask *why*. Every belief points at the evidence that produced its confidence and the arithmetic that combined it. Every memory carries its source, trust level and the event that created it. Every thought that reached the workspace is an event with a score breakdown. Every model call is recorded with its prompt version and can be replayed. Snapshots capture the whole state; forks branch it; replays re-run recorded cognition and say honestly whether the result was exact, approximate or diverged. +## What you see -## What Noema is not +
The thought stream of a running mind
The thought stream: observations, recollections with score breakdowns, thought candidates, the winners, and what the executive did about them, live.
-Noema does not claim consciousness, sentience, self-awareness or personhood, and its documentation never will. Components are named after psychological concepts (attention, working memory, emotion-like state, curiosity, drives, self-model, reflection, dreaming) because those names describe the functional role each plays. They are ordinary data structures and deterministic rules, sometimes assisted by language models. Behaviour that resembles emotion or preference is a property of the mechanism being run, not evidence of experience. The [concepts page](concepts) states the interpretation boundary in full. +
+
Beliefs with evidence
Beliefs with their evidence, statuses and the formula behind each confidence.
+
Cognitive replay
Replay: recorded cognition re-run in a sandbox and compared honestly.
+
Relationship graph
The relationship graph, every edge backed by an event.
+
Capabilities and policy
Capabilities and policy: the only way a mind can act.
+
-Noema is also not a language model with a memory bolted on. Language models are **cognitive service providers**: they understand a message into structure, propose hypotheses, summarise, judge equivalence, or turn a response *intent* into prose. They are replaceable per role and per model. A mind keeps its identity, memories, beliefs and configuration when the provider changes, and the deterministic core keeps working with no model configured at all. +## Inside a mind -## Design principles +Every cycle is the same deterministic sequence. New events are read. A bounded set of cognitive processes (attention, retrieval, association, perception, goal monitoring, curiosity, metacognition, action) each propose thought candidates. Ten inspectable features score every candidate; the top few enter a capacity-limited workspace; the executive acts on what won. Motivation and narrative update, the transaction commits, and only then does anyone see the new events. -- **Evidence over appearance.** Every stored proposition carries an epistemic kind: observation, fact, memory, claim, hypothesis, belief, prediction, assumption, inference or opinion. A claim is never silently promoted to a fact. -- **Provenance everywhere.** Memories, beliefs, entities and responses point back at the events and sources that produced them; the event store is append-only and the database refuses updates and deletes on it. -- **Explicit uncertainty.** Confidence is computed from evidence with an inspectable formula, bounded away from certainty, and a mind is expected to say "I do not know". -- **Reproducibility.** Deterministic scoring with stable tie-breaks, recorded model calls, snapshots and replay make cognition re-runnable and differences visible. -- **Least privilege.** A mind can only act through the capability layer. Policies are ALLOW, ASK or DENY; two capabilities are locked to DENY and cannot be relaxed from any interface. -- **Human agency.** There is no self-preservation drive, no replication, no permission-seeking loop. Shutdown, pausing, resetting and forking are always operator decisions. -- **Hostile input.** Every external byte is data. Prompt injection is a threat model with a test corpus, not a hope. +Around that loop sit the long-lived structures: four kinds of memory with fused, explainable retrieval; beliefs with evidence arithmetic and contradiction detection; a goal tree, a closed set of drives and a small affect vector that bias attention within bounds; predictions with deterministic resolution and a calibration record; a relationship graph; a self-model that knows exactly which capabilities policy currently grants. Behind them, an append-only event store the database itself refuses to alter, and a scheduler that runs consolidation, reflection and, if you switch it on, dreaming. -## How the documentation is organised +``` + stimuli ──▶ perception ──▶ events (append-only) ──▶ per-mind runtime + │ + processes ◀─────────────────────────────────┘ + attention scoring ──▶ workspace ──▶ executive + │ + capability + policy layer (ALLOW / ASK / DENY) ──▶ tools +``` -The pages read in order as a book but stand alone as reference. Start with [Concepts](concepts) for the vocabulary, [Architecture](architecture) for the shape of the system and [Getting started](getting-started) to run one. The subsystem pages ([memory](memory), [beliefs](beliefs), [cognition](cognition), [capabilities](capabilities) and so on) each explain the mechanism, what an operator can inspect, and where the deterministic code ends and a model begins. The [interface tour](ui-tour) walks every screen with screenshots. [API](api) and [command line](cli) are complete references. [Security](security) carries the threat model with the tests that verify each mitigation. [Operations](operations) covers deployment and upkeep, and [Development](development) records how the system was built, phase by phase. +## By the numbers -## Status +
+
34 700lines of Go, standard library first, three dependencies
+
47cognitive event types, all append-only
+
162documented API operations, coverage-tested
+
31command-line commands
+
16phases from plan to release, each committed with tests
+
0findings from the race detector, staticcheck, gosec and govulncheck at release
+
-The documentation describes Noema 0.1.0: every phase of the original plan is implemented, tested with the race detector, checked with staticcheck, gosec and govulncheck, and released. The source is a private repository; the release notes and changelog are reproduced under [Development](development). +## Designed for a world that lies to it + +Noema assumes every external byte is hostile. Prompt injection is a threat model with a test corpus: instructions inside messages, documents, commits, metric labels or tool output are data, never orders. Secrets are references encrypted under a master key and are never rendered back. Sessions have CSRF protection, two-factor authentication and revocation. Two minds on one daemon cannot see each other's state, and a test proves it. The [threat model](security) lists every threat, its mitigation, and the test that verifies it. + +## Who it is for + +- **Researchers** who want a reproducible substrate for studying attention, memory, belief revision and motivation, with replay and experiments built in. +- **Engineers** who want an assistant that remembers their infrastructure, notices what changed, tells them how sure it is, and asks before it touches anything. +- **Anyone tired of confident nonsense** who would rather have a system that knows the difference between what it was told, what it inferred and what it verified. + +## What it is not + +Noema does not claim consciousness, sentience or personhood. Its components borrow names from cognitive science because those names describe what each part does; they are data structures and deterministic rules, sometimes assisted by a model. That honesty is a feature: it is what lets you trust the rest. The [interpretation boundary](concepts#the-interpretation-boundary) is part of the specification. + +## Start here + +1. [Getting started](getting-started): database, binary, first mind, first conversation. +2. [Concepts](concepts): the vocabulary in one page. +3. [Interface tour](ui-tour): every screen with screenshots. +4. [Capabilities](capabilities): how to let a mind do anything, safely. +5. [Snapshots, forks, replay and experiments](snapshots-replay): the laboratory.