Okto Neuron

Okto Neuron by Okto Labs. Local-first knowledge graph memory for agents, with cited sources and an MCP server.

Okto Neuron was developed under the working name Marginalia. Every release up to 0.2.0 was published as marginalia from the OktoLabsAI/marginalia-dist repository. From 0.3.0 the product, the package, the command and this repository are named Okto Neuron. The 0.3.0 line builds on an earlier Okto Neuron MVP by João Braga (2026-09), which is archived as OktoLabsAI/okto-neuron-mvp; see ADR 0044.

Upgrading from Marginalia (0.3.0)

0.3.0 is a rename release. Nothing about how a vault stores or answers changes, and existing vaults are opened where they are.

| Before (up to 0.2.0) | From 0.3.0 | What still works | |---|---|---| | marginalia command | okto-neuron command (kg is unchanged) | marginalia keeps working and prints a rename warning until 0.5 | | MARGINALIA_* environment variables | OKTO_NEURON_* | the old name is read with one warning until 0.5; when both are set the new one wins | | ~/.marginalia app home | ~/.okto-neuron | app files (marginalia.toml, env, providers.yaml, defaults.yaml) are copied over once; ~/.marginalia/vaults is not moved and stays a vault root, because document ids hash absolute paths | | marginalia.yaml in a vault | okto-neuron.yaml for new vaults | an existing marginalia.yaml is read and written in place and never renamed; a vault's .marginalia/ state directory keeps its name | | X-Marginalia-Vault header, marginalia_version field | X-Okto-Neuron-Vault, okto_neuron_version | both old names are still accepted and sent | | MCP server marginalia | MCP server okto-neuron (tools become mcp__okto-neuron__*) | the daemon keeps its port and credential; the installer replaces a user- or local-scope marginalia entry, and an entry in any other client keeps connecting until you rename it | | import marginalia | import okto_neuron | none: there is no marginalia import shim, because that name belongs to an unrelated PyPI package |

The installer in this repository does the upgrade for you: it finds the marginalia uv tool, stops its daemon with that tool's own command, installs okto-neuron, copies the app files, and registers okto-neuron with Claude in the same scope (user or local) as your existing marginalia entry. Once okto-neuron answers Claude's connection check, the installer removes the old marginalia entry from that same scope; if the installer fails after that, it adds the old entry back. A project-scope entry in a shared .mcp.json is left for you to rename. If anything fails before the new version is verified, the exact previous marginalia tool is restored.

To upgrade by hand instead, stop the old daemon with marginalia stop, run uv tool uninstall marginalia, install with uv tool install "okto-neuron[serve,litellm]", then run okto-neuron migrate-home once to copy the app files. If the old daemon is still running (for example after uv tool install --force), okto-neuron serve refuses to start while it holds ~/.marginalia/runtime, and okto-neuron stop stops it.

The ChatGPT-subscription provider stays opt-in and is marked experimental: it needs OKTO_NEURON_ENABLE_CHATGPT=1, and OpenAI's terms for consumer subscriptions may not allow access from third-party tools. Read them before enabling it (docs/remote-providers.md).

Known issues

• Large documents on the Grafx backend: ingesting a single document longer than 65,536 characters fails on the default Okto Grafx backend. Split the file, or create the vault with --backend ladybug or --backend neo4j. It is an open issue in the issue tracker ("grafx fails on documents over 65,536 characters").
• Snapshot race on Ladybug: kg snapshot dump can read graph.lbug between the two renames of a concurrent staged commit and see a mix of pre- and post-swap rows. It reproduces since v0.1.0 and is tracked by tests/store/contract/test_snapshot_concurrency.py::TestLadybugSnapshotPinnedDumpVsSwap::test_dump_never_mixes_pre_and_post_swap_rows. Do not dump a Ladybug vault while a rebuild, heal or reembed is committing.

Release history (published as Marginalia)

Versions up to 0.2.0 were published as Marginalia, under Apache-2.0, from the marginalia-dist installer repo. Release notes and wheels stay on its releases page.

| Version | Published | Status | |---|---|---| | 0.2.0 | 2026-09-23 | Prerelease. Reliability release on the 0.1.0 MCP surface: provider login / provider status chatgpt, transient provider errors retried in ask and in every ingest judge and curator step, two sealed-plan wedges fixed, remember write failures logged on MCP and REST, Neo4j driver errors translated. | | 0.1.0 | 2026-09-18 | Prerelease. The agent-facing MCP surface: five tools, ask widened to 17 parameters, include_sources, synthesis_status on every ask (ADR 0043). | | 0.0.50 | 2026-09-17 | Prerelease. Ingest-quality release. | | 0.0.44 to 0.0.49 | 2026-07-29 to 2026-09-14 | Prereleases. | | 0.0.43 | 2026-07-14 | The last release published as stable. | | 0.0.42 | 2026-07-14 | Prerelease. Its release asset was replaced after publication, so it is not an immutable release. | | 0.0.41 | 2026-07-14 | Prerelease, not eligible for promotion: a native Windows run failed. | | 0.0.40 | 2026-07-13 | Not eligible for promotion. |

For 0.0.47 through 0.2.0 the release gates (model-free suite, acceptance, eval floor, wheel checks) were run locally rather than on hosted CI. A Linux Docker+tmux install rehearsal from the public raw installer URL passed for 0.0.47, 0.0.50, 0.1.0 and 0.2.0. No published version has passed a real interactive Windows PowerShell 5.1 lifecycle, so Windows install is not yet a validated path. The snapshot race listed under Known issues was present in 0.1.0 and 0.2.0.

Compatibility note from 0.0.41: two client-derived public spellings were replaced without aliases, as privacy-neutralizing breaks. budgets exports CORPUS_BUDGET_SECONDS and budget_check() takes the corpus suite key; callers using the old constant or key must migrate. pilot reports use the pilot-log.YYYY-MM-DD.json basename.

Okto Neuron is a standalone, local-first knowledge graph usable as a Python library, CLI (okto-neuron / kg), and authenticated MCP server. Your Markdown vault is the trust root; the graph is derived from it and can always be rebuilt. See RFC.md for the full design and docs/index.html for the documentation hub (Roadmap · Understanding · Knowledge Base · RFC).

What it does

• Ingest Markdown into a real graph. Files are chunked, LLM-extracted into atomic claims and entities, embedded, and stored in a pluggable graph store — Okto Grafx by default, with Ladybug and Neo4j selectable via --backend (see docs/backends).
• Answer with graph retrieval and source grounding. Hybrid retrieval (dense + BM25) selects graph hits, and ask() synthesizes over their byte-anchored source-block context by default. Graph-native subgraph assembly is opt-in; explore() walks the graph with no LLM.
• Living memory. remember() extracts, deduplicates, reconciles entities, and supersedes stale claims on every ingest. A folder watcher keeps a vault in sync as files change.
• Provenance you can trust. The atomic unit is a Claim — one subject- predicate-object assertion — anchored by PROV-O edges to its source Block, the extractor Activity, and the responsible Agent.
• Surfaces over one core. A sync CLI, an async FastMCP server (five tools: ask, explore, remember, list_vaults, init_vault), a Python SDK, and a built Web UI converge on the same Vault/Companion core. The small okto_neuron.api module is the compatibility export for library callers, not the implementation layer for every surface.

Schema

The schema is closed at 5 primitives — Agent, Activity, InformationObject, Concept, Place — plus 6 support types — Document, Identifier, Annotation, Claim, Block, Finding. Vault configuration can select the fixed built-in label/edge registries (core, research, personal, sdlc); external manifest packs are not a production plug-in surface. Adding a sixth primitive requires a new RFC and code change. Field and edge names follow the canonical vocabulary (PROV-O, SKOS, Dublin Core, BIBFRAME, CiTO, W3C oa:Annotation) rather than coined terms.

Install

From 0.3.0 the installer and its SHA-256 release manifest live in this repository, and wheels are GitHub Release assets here and on PyPI as okto-neuron. Until 0.3.0 is published, the marginalia-dist one-liner below keeps installing 0.2.0; after that it forwards to this installer. The installer starts the local application, opens it in the default browser, and does not choose a vault on the user's behalf; on a fresh interactive terminal with no existing vault or config (greenfield + TTY) it additionally asks once, after installing the tool and before starting the app, whether to run the terminal okto-neuron onboard flow (Y/Enter runs it, n keeps the application-first path), and skips that prompt for piped/CI installs (no TTY), OKTO_NEURON_NO_OPEN=1, OKTO_NEURON_VAULT preseeding, the --no-onboard flag, and every reinstall or upgrade. The PowerShell installer resolves the same release on Windows; there is still no retained native PowerShell 5.1 lifecycle evidence for any published version (the 0.0.41 Windows daemon lifecycle is known broken), so treat that path as unverified. The raw manifest pins the exact wheel and checksum.

# macOS / Linux (0.3.0 and later)
curl -fsSL https://raw.githubusercontent.com/OktoLabsAI/okto-neuron/main/install.sh | bash

# Windows PowerShell (0.3.0 and later)
powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/OktoLabsAI/okto-neuron/main/install.ps1 | iex"

# PyPI (0.3.0 and later), as a uv tool
uv tool install --python 3.12 "okto-neuron[serve,litellm]"

# 0.2.0 (published as Marginalia), the current published prerelease
curl -fsSL https://raw.githubusercontent.com/OktoLabsAI/marginalia-dist/main/install.sh | bash

A fresh vault's graph backend is Okto Grafx by default — no --accept-experimental flag or extra install step needed, it is a base dependency of the package. Pass --backend ladybug or --backend neo4j at creation time to opt into one of the other two fully supported, selectable backends instead. See docs/backends/grafx.md, docs/backends/ladybug.md, and docs/backends/neo4j.md.

Direct Python consumers install okto-neuron (0.3.0 and later) or the exact wheel file or release URL. Never install the unrelated PyPI packages named marginalia or neuron. The direct-wheel contract below describes the released 0.2.0 wheel; it does not retroactively describe the immutable public predecessor wheels named in the release status history above. The repaired base wheel supports package imports, --version, command help, and actionable missing-feature errors; graph-backed library work adds [ladybug]. [serve] is the preferred complete application-server boundary (Ladybug + FastMCP + embeddings), while [mcp] is an identical compatibility alias for earlier install guidance. JSON-LD/JSON-LD-star export adds [jsonld], which supplies RDFLib. Clean-wheel tests execute these composed features separately so a combined full-extras environment cannot mask an incomplete dependency contract.

The public distribution installer provisions `u