The Athanor

Make AI tools better at real work.

The Athanor gives a tool-capable AI bounded access to the projects, decisions, lessons, and prior work it needs for the current task. Retrieved material keeps its source attached. Corrected knowledge can replace stale guidance without erasing history. The model or provider carrying the work can change without making the project start from zero again.

Status: native Windows x64 late beta. OMP is the supported harness. The earlier source snapshot used 0.9.6. Read package.json for the current product version. One Rust workspace owns the behavioral core, Vault retrieval, AKASHA PostgreSQL authority, Athanor Host, NATS delivery, native lifecycle, and parked Godot client. Vault remains database-free; AKASHA adds durable typed memory, lessons, canon, continuity, and governed background work.

The historical installation proof used the build labeled 1.0.0-rc.3. It used external database authority, separate Kintsu and Kodo Hosts, and one stable OMP loader. That label identifies the retained artifact and its evidence. It does not identify the current installation or establish product maturity. Read the installed manifest for active bytes and dated evidence for exercised behavior.

See it: open the public interface specimen. It uses sanitized browser-only fixtures and makes no Host, database, delivery, or persistence claim.

Choose your entrance

The project has one architecture and three useful ways into it:

Read the diagram source

flowchart LR
    A[The Athanor] --> W[Make my AI tools better at work]
    A --> X[Explore the cognitive architecture]
    A --> E[Explain it to agents or people]
    W --> V[Vault first]
    X --> H[Houses, authority, retrieval, GIGA]
    E --> G[Canonical concept graph and explanation paths]

The older adversarial introduction was not discarded. It moved behind the second door, where a reader asking for the architectural argument can meet it on purpose instead of being mugged by the reception desk.

Better context for ordinary work

A normal user does not need to care about memory theory. They need the AI to answer questions like:

Which service owns invoice validation, what decision changed it, and where is that documented?

Without a retrieval layer, an agent must guess, reread an arbitrary pile of files, or ask the operator to reconstruct the project again. The Athanor gives it a bounded evidence path instead:

Read the diagram source

flowchart LR
    Q[Current task] --> R[Retrieve relevant evidence]
    F[Project files] --> R
    M[Prior decisions and lessons] --> R
    R --> C[Attributed context]
    C --> A[Tool-capable AI]
    A --> O[Work and observable receipts]

The Athanor does not make a model infallible. It makes the context path visible: which source was selected, which terms or fields matched, what authority the record has, and where a correction belongs.

Start with Vault

Vault is the lightweight profile. In the room's .athanor-room.json, point it at one or several project roots:

{
  "vaultRoots": ["../project-a", "../project-b"],
  "vaultIgnore": ["private/**", "generated/**"],
  "vaultMaxFileBytes": 524288,
  "vaultMaxFiles": 5000
}

Vault searches Markdown, JSON, JSONL, and plain text using exact-content and field-aware BM25F lanes. Results contain bounded excerpts with source path, heading or record identity, matching fields, selection reasons, and term coverage. Its index is derived from the configured files and rebuilt as needed.

Vault requires no PostgreSQL, embeddings, or GPU. It excludes common generated paths and secret-bearing filenames, respects configured ignores and each root's top-level .gitignore, and does not follow symlinks.

Read Retrieval for the exact query, attribution, and limit contracts.

Local workspace search for OMP

The optional Node adapter in adapters/workspace-search uses zvec-grep with local Ollama Nemotron embeddings. It searches repository files. It does not change Vault, AKASHA, or the Host. Node 24 or later and the following installed Ollama model are required:

hf.co/zenmagnets/Nemotron-3-Embed-1B-Q4_K_M-GGUF:latest

Install the adapter from the repository root:

pwsh -NoProfile -File adapters/workspace-search/install.ps1

The installer retains a hashed package archive under ~/.omp/tools/athanor-workspace-search. It installs pinned dependencies and replaces the zvec_grep entry in the OMP MCP configuration. Restart OMP to load the installed server.

Index one repository explicitly:

$entry = "$HOME/.omp/tools/athanor-workspace-search/node_modules/@solarisael/athanor-workspace-search/dist/cli.js"
node $entry index --root C:/Projects/my-repository
node $entry search --root C:/Projects/my-repository --query "Which module owns request cancellation?"
node $entry status --root C:/Projects/my-repository

Repeat the index command to update changed files. Use another absolute root to index another repository. Search never creates an index. A missing index returns INDEX_MISSING. An ordinary search does not refresh the index or check every file. Returned snippets carry their own freshness state. Search returns five hits per query group by default, with at most 2000 characters of content per hit. The contentTruncated flag marks clipped excerpts. Metadata is additional. Use zvec for discovery, then native grep and read once the relevant path or symbol is known. Set --limit explicitly when you need more results. Use --autoUpdate for an inline refresh before a search. Use status to inspect changes and failed files.

Warning: index --rebuild discards the existing derived index. Use this option only when you explicitly need a rebuild. The adapter never changes repository source files. The model uses 2048 dimensions, a 4096-token context, and distinct query and passage prefixes. The index uses a smaller 1024-token chunk budget because zvec estimates size from characters. Oversized embedding inputs fail instead of being silently truncated.

The MCP server exposes zvec_grep_search, zvec_grep_index, and zvec_grep_status. Use the CLI for long initial builds. There is no background watcher. Keep Lumen enabled until the new adapter passes an index and search check. Then disable its OMP plugin:

omp plugin disable lumen@claude-plugins-official

Grow into AKASHA when the work needs it

AKASHA adds a durable PostgreSQL authority layer, pgvector, pg_trgm, local embeddings, typed memory and lesson stores, supersession, chronology, taxonomy, and governed lifecycle operations.

This is a deployment choice, not a maturity contest. Vault can be the complete answer for a project corpus. AKASHA is for work that needs durable typed knowledge, deeper continuity, and governed cognitive machinery.

The current architecture

Read the diagram source

flowchart TB
    U[Operator] --> GUI[Web prototype: read-only]
    U --> OMP[OMP harness]
    GUI --> PROXY[gui-prototype/serve.ts: loopback proxy]
    PROXY -->|allowlisted POST-only /live/* read routes| HOST[Athanor Host]
    OMP --> AD[Thin OMP adapter]
    AD --> RUST[Shared Rust core and protocol]
    HOST --> RUST
    RUST --> VAULT[Vault: file-authoritative retrieval]
    RUST --> AKASHA[AKASHA: PostgreSQL authority]
    AKASHA --> OUTBOX[Transactional outbox]
    OUTBOX --> NATS[NATS JetStream]
    NATS --> HOST
    AKASHA --> GIGA[GIGA candidates and typed lessons]

Authority stays explicit:

Read the diagram source

flowchart LR
    P[PostgreSQL authority] --> C[Canon]
    C --> M[Memory and typed lessons]
    M --> R[Retrieved evidence]
    R --> CTX[Bounded model context]
    G[GIGA candidates] -. proposal only .-> M
    H[Historical Markdown] -. provenance .-> M

In AKASHA, PostgreSQL is authoritative, canon outranks loose memory, and retrieval rank does not create truth. A GIGA candidate remains a proposal until an authorized promotion. Anamnesis is counsel, never canon.

Read Architecture for component and data-flow contracts and Hippocampus for candidate authority.

What exists now

These capabilities have source implementations and dated installation evidence. The 0.9.6 label belongs to an earlier source snapshot.

• one shared Rust contract layer and Rust-owned Vault/AKASHA behavior;
• strict database-free Vault retrieval with attributed bounded evidence;
• PostgreSQL-authoritative canon, memory, typed lessons, continuity, and GIGA;
• typed Paper Boat sleep/wake with transaction-coupled boat.ready outbox rows;
• NATS JetStream delivery carrying only bounded sanitized pointers and receipts;
• an authenticated localhost Athanor Host with persisted snapshots, typed deltas, resynchronization, idempotency, and restart recovery;
• a read-only web operator surface at gui-prototype/;
• a parked Godot 4.7.1 client with Recall Policy and sanitized Paper Boat receipt screens;
• one native Windows service supervisor, installer, updater/rollback path, doctor, uninstall, and explicit purge boundary;
• named OMP organs whose adapter delegates behavioral authority to Rust.

Critical organ review — 2026-09-06

The House must turn preserved records into useful continuity, judgment, and completed work. A stored record, a delivered message, and a useful outcome require separate evidence. The review proposes this dependency sequence:

1. Make orientation coherent across models, turn sources, and interrupted sessions.
2. Make outcomes attributable and visible through Pulse.
3. Complete permitted exchanges through Hallway, Docket, and worker dispatch.
4. Connect reviewed learning to later useful behavior.

Current gaps include combined context size, temporal orientation, and full backups after individual writes. GIGA's queue status does not establish useful consolidation. Curio storage does not establish automatic resurfacing. The web operator surface remains read-only.

The generated-turn Presence repair is installed and passes isolated component checks. A new OMP session must load it. Real restart, chat, and root Knock turns now have live incoming Presence observations. Host-side session attribution remains separate work.

Read the organ review for each organ's evidence, gap, and proposed outcome. The 2026-09-06 review changed records and planning. Later implementation receipts remain separately dated.

What remains before 1.0

The web prototype at gui-prototype/ is the read-only operator surface. Run bun gui-prototype/serve.ts from the repository root. It reads the Host through a loopback proxy. The Godot client is parked. Conversation, authority changes, review actions, and complete operational visibility remain incomplete.

The 1.0 gate also requires healthy live continuity organs, clean generic installation, a real legacy upgrade and rollback, signing, and bounded public release evidence. The in-world 3D room, Datalog/Lean proof paths, Cingulate, OMEGA, ANON, Relay, group rooms, and the signed marketplace remain later work and do not block 1.0.

The current late beta does not claim proven token savings, improved answer quality, support beyond Windows x64 + OMP, provider-side privacy, enterprise tenancy, or clean-machine installation evidence.

Planned Features is the canonical status map. Evidence separates measurements from hypotheses. Limitations names the release boundary.

Install

One repository and one release own the substrate, Host, delivery, OMP adapter, parked Godot client, installer, updater, and install contract.

The supported ordinary package is one checksum-published native Windows x64 installer:

The-Athanor-<version>-windows-x64.exe
The-Athanor-<version>-windows-x64.exe.sha256

It carries the Rust runtime binaries, parked Godot 4.7.1, EnterpriseDB PostgreSQL 18.4-2 with pgvector 0.8.6, and NATS Server 2.14.4. The installed service needs no WSL, Python, Bun, Cargo, or separate database/broker. The bundled Godot client is parked. PostgreSQL remains the durable AKASHA authority; Vault retrieval remains available as a runtime capability rather than a separate package.

Immutable product versions live under %ProgramFiles%\Solarisael\Athanor\versions. Mutable databases, rooms, backups, configuration, logs, and ACL-restricted secrets live under %ProgramData%\Solarisael\Athanor and survive ordinary uninstall. An explicit advanced mode uses an operator-provided external PostgreSQL 18 + pgvector 0.8.6 database while retaining the other packaged components.

Installation verifies every staged artifact before activation, backs up before upgrade, runs ordered migrations, and requires Windows service readiness. Rollback uses the retained version pointer and pre-change database backup. A bounded legacy pre-install door only imports and backs up named 0.10.x trees; no legacy runtime is retained.

Read Install The Athanor for checksum verification, exact topology, external-database configuration, rollback, uninstall, and explicit purge contracts.

Repository boundaries

All three live in solarisael/the-athanor and ship in one release. Read Repository layout and component ownership for the full contract.

The core is designed around provider-neutral contracts. That does not mean every harness already has a supported adapter.

Documentation

Use it

1. Install
2. Daily usage
3. The Athanor for work
4. Identity guide

Understand the current system

1. Architecture
2. Retrieval
3. Lessons
4. Hippocampus
5. Evidence
6. Security
7. Limitations

Explore or explain it

• For latent-space explorers
• Explaining The Athanor
• The House model and project history
• Grouped documentation index

Follow accepted direction

• Changelog — active 0.9.6 work and retained RC build history
• Planned Features — canonical status map
• Runtime Architecture
• Parked Godot Client
• Synthesis Architecture
• Companion Ecosystem

Dated snapshots under docs/history/ are provenance, not current release contracts.

License

The Athanor uses the Apache License 2.0. See LICENSE and NOTICE.