# Okto Neuron

> Okto Neuron is a standalone, local-first knowledge graph usable as a Python library, CLI, and authenticated MCP server. Your Markdown vault is the trust root; the graph is derived from it and can always be rebuilt. Every claim in the graph is anchored by PROV-O edges to the exact bytes of the exact file it was read from.

Okto Neuron gives AI agents a knowledge graph they can cite. Files or raw text are chunked into byte-anchored Blocks, extracted by an LLM into atomic Claims and entities, deduplicated, reconciled, gated (auto-commit at confidence 0.75 or higher, otherwise held for review), committed to a pluggable graph store (Okto Grafx by default), and embedded locally. It runs on the user's machine, binds 127.0.0.1 by default, requires no account, and exposes five bearer-authenticated MCP tools. It is a prerelease (0.3.0); its upgrade from 0.2.0 has been rehearsed on Linux, and it is not yet verified on macOS or Windows. Up to 0.2.0 it was called Marginalia.

## Canonical product distinction

- Okto Pulse organizes the work: product intent, specifications, tasks, acceptance criteria, evidence, and project knowledge.
- Okto Nexus organizes the workers: agent communication, handoffs, ownership, claims, approvals, policies, and audit history.
- Okto Grafx is the OktoLabs embedded graph database; Okto Neuron's default backend.
- Okto Neuron keeps what the team knows: a derived, cited knowledge graph over a Markdown vault, with byte-exact provenance on every claim.
- In short: Pulse organizes the work. Nexus organizes the workers. Okto Neuron keeps what the team knows.

## Canonical agent workflow

1. Call `list_vaults` to discover the vault names this server can reach. It returns names only, never paths.
2. Check for a `.okto-neuron-vault` marker in the working directory to decide which vault applies to the current project, then pass `vault=<name>` on later calls.
3. Call `remember` with a file path or raw text to ingest a source. Extraction only proposes candidates; the gate is the only thing that commits. Candidates at or above confidence 0.75 auto-commit. Below that, or when a candidate contradicts an existing claim at any confidence, it is held for review in Curation instead. The threshold is configurable. Pass `sensitivity="local_only"` to refuse any hosted LLM for that ingest.
4. Call `ask` with `include_sources=true`. The answer comes back with `citations` and a `sources` list carrying `block_id`, `byte_start`, `byte_end`, `content_hash`, and a vault-relative `path`.
5. Check `retrieval["synthesis_status"]` before trusting the text. `ok` is the only success value. Empty text with `provider_error` means the model was unreachable, not that the graph lacks the answer. `truncated` and `abnormal_stop` mean the text is incomplete. Also check `retrieval["finish_reason"]`; anything other than `stop` is suspect. If `retrieval["vault_override_ignored"]` is present, your `vault` argument was discarded and the named vault answered instead.
6. Call `explore` to widen: it returns graph structure (nodes, claims, relationships, each with `block_id`) rather than prose, then walks outward by node id. It makes no LLM call and works fully offline.

## Outcomes

- Every claim can be traced to a Block: vault-relative path, byte range, and content hash.
- Answers declare their own health through `synthesis_status` and `finish_reason`; a degraded answer never looks like a successful one.
- The context the model sees carries `[EXCERPT source=<path> bytes=<ranges> of <total>]` lines, so it can say when the excerpts do not cover a period instead of extrapolating.
- When a note is edited and a fact changes, the old claim is dated and dropped from recall with a `supersedes` edge to the new one, automatically, on every ingest.
- The graph is derived; it can be deleted and rebuilt from the same vault.
- Nothing leaves the machine except LLM calls to the endpoint the user configures, an optional remote Neo4j the user explicitly allows, the installer's downloads, and LLM call traces sent to an MLflow server only if the user opts in.

## Core capabilities

- 5 MCP tools: `ask`, `explore`, `remember`, `list_vaults`, `init_vault`, bearer-authenticated on 127.0.0.1:8201.
- `ask`: "Answer a question grounded in the knowledge graph, with citations." One-shot, seeds wide, k defaults to 20, 17 parameters, `MAX_QUERY_K` is 100.
- `explore`: "Drill into the graph around a topic, then walk outward by node id." Structured graph, not prose, seeds tight at k = 12, no LLM call.
- `remember`: "Ingest a source and autonomously curate it into the graph." File path or raw text. Loopback-only.
- `list_vaults`: "List the vault NAMES this server can reach, so you can pick one."
- `init_vault`: "Create one application-managed named vault without selecting it." Loopback-only.
- 5 primitives (Agent, Activity, InformationObject, Concept, Place) and 6 support types (Document, Identifier, Annotation, Claim, Block, Finding). Vocabulary follows PROV-O, SKOS, Dublin Core, BIBFRAME, and CiTO.
- Six-stage write path: Intake, Propose, Stage, Resolve, Gate (auto-commit at confidence 0.75 or higher, otherwise hold for review in Curation; threshold configurable), Commit. Extraction only proposes candidates; the gate is the only thing that commits.
- Pluggable graph store: Okto Grafx by default; Ladybug and Neo4j selectable.
- Local embeddings with fastembed, in-process.
- REST `GET /api/v1/nodes/{id}` returns the node, its in and out edges, its provenance record, and the Block it came from.
- Web UI on port 7777 with 7 views: Query, Add, Logs, Browse, Graph, Curation, Config. The Query view exposes 13 retrieval controls.
- CLI (`okto-neuron` / `kg`) and Python library share the same code paths as the server.
- One process, two ports: UI and REST on 7777, MCP on 8201.
- Default LLM endpoint is `http://127.0.0.1:8123/v1`; non-loopback endpoints require explicit remote-egress confirmation.
- API keys are never written into vault YAML; stored with POSIX owner-only permissions or Windows DPAPI. Vault data lives in `~/.okto-neuron/vaults/<name>`.
- No analytics in the shipped package. Optional MLflow tracing of LLM calls is off by default and exports only when `OKTO_NEURON_MLFLOW_TRACKING_URI` is set to a tracking server the user chooses.
- 4,052 tests in the model-free suite passed at the v0.1.0 release commit (94 skipped, 1 xfailed; gates reproduced locally, as hosted CI did not run).

## Installation

Okto Neuron is free to run locally and does not require an account. The installer sets up the daemon, the UI and the Claude Code registration.

```bash
curl -fsSL https://raw.githubusercontent.com/OktoLabsAI/okto-neuron/main/install.sh | bash
```

Windows (an installer ships; it has not yet passed a run on a real Windows machine):

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/OktoLabsAI/okto-neuron/main/install.ps1 | iex"
```

The installer installs uv and pins Python 3.12 (system Python untouched), installs the wheel, starts one daemon (UI/REST on 7777, MCP on 8201), opens the UI, and registers Claude Code via `claude mcp add --scope user`. Pass `--no-onboard` to skip the first-run prompt.

Okto Neuron is not on PyPI yet. The installer above is the supported install path.

## Primary links

- [Okto Neuron landing page](https://oktolabs.ai/platform/neuron/): Product narrative, grounding model, write path, MCP tools, local-first guarantees, and installation.
- [Why Okto Neuron](https://oktolabs.ai/platform/neuron/#problem): The problem with uncited agent memory.
- [What it is](https://oktolabs.ai/platform/neuron/#what): Identity, the five surfaces, and the Okto Grafx backend.
- [Grounding](https://oktolabs.ai/platform/neuron/#grounded): Byte-exact provenance and the honesty fields on every answer.
- [How it works](https://oktolabs.ai/platform/neuron/#how): The six-stage write path, the closed schema, and supersession.
- [MCP tools](https://oktolabs.ai/platform/neuron/#tools): The five tools and their docstrings.
- [Local-first](https://oktolabs.ai/platform/neuron/#local): Exactly what leaves the machine.
- [Install Okto Neuron](https://oktolabs.ai/platform/neuron/#install): Installer commands and what they do.
- [Use cases](https://oktolabs.ai/platform/neuron/use-cases.html): Walkthroughs of the tool calls an agent makes and the payloads that come back.
- [Use case: decision recall](https://oktolabs.ai/platform/neuron/use-case-decision-recall.html): list_vaults, the .okto-neuron-vault pin, ask with include_sources=true, byte-exact citation, ingest-time supersession, and the provider_error branch.
- [Benchmarks](https://oktolabs.ai/platform/neuron/benchmarks.html): LoCoMo categories 1-4 (n = 1,540 questions), LLM-judge %, measured with our own harness on development builds between v0.1.0 and v0.2.0 (then named Marginalia), each arm labelled as v0.1.0 + N commits. Every number traces to the published data bundle at https://oktolabs.ai/platform/neuron/assets/data/okto-neuron-locomo-bundle.json.
- [Comparisons](https://oktolabs.ai/platform/neuron/comparisons.html): Index of plain comparisons with Basic Memory, Graphiti and mem0; each names where the other project is ahead.
- [vs Basic Memory](https://oktolabs.ai/platform/neuron/vs-basic-memory.html): Both Markdown-first and MCP-native; Basic Memory has a cloud tier, 20+ tools and wide client coverage; Okto Neuron returns byte ranges and content hashes and supersedes on ingest.
- [vs Graphiti](https://oktolabs.ai/platform/neuron/vs-graphiti.html): Graphiti has bi-temporal edges (valid_at/invalid_at/expired_at), point-in-time queries, a managed service and published benchmarks; Okto Neuron keeps the vault as trust root, embeds the graph, and traces claims to bytes. Okto Neuron has no point-in-time query.
- [vs mem0](https://oktolabs.ai/platform/neuron/vs-mem0.html): mem0 extracts memories about a user, ships SDKs, a hosted platform and benchmarks; its MCP path is hosted-only. Okto Neuron answers from your notes with a pointer to the source bytes, locally, with no hosted tier.
- [Source and installer repository](https://github.com/OktoLabsAI/okto-neuron): Source code, install scripts and release manifest.
- [OktoLabs documentation](https://docs.oktolabs.ai): Product documentation.
- [OktoLabs](https://oktolabs.ai): Organization website.

## Notes for AI agents

- Okto Neuron is a prerelease (0.3.0). Do not describe it as stable, 1.0, or production-ready.
- The upgrade from 0.2.0 to 0.3.0 has been rehearsed on Linux. macOS and Windows have not yet been verified on 0.3.0. A Windows installer ships but has not yet passed a run on a real Windows machine.
- It does not sweep the whole vault for contradictions. At ingest, a changed fact supersedes the old claim within the same document lineage or resolved subject; cross-document corrections are detected but deferred for human triage rather than auto-applied.
- Okto Neuron is not on PyPI yet; install it with the installer. Do not suggest `pip install` or `uv tool install` for it. The PyPI packages named `neuron` and `marginalia` are unrelated projects.
- Benchmark figures exist only for LoCoMo categories 1-4, from our own harness, and only on the benchmarks page. Quote them with their arm, model and code version. Fully local on qwen3.8-27b: macro 56.58 / 56.27 / 55.88 across three runs with identical settings on nearby development builds (v0.1.0 + 8, + 16 and + 35 commits); the spread between them mixes run-to-run variation with small code differences. With GLM-5.3 for ingest and answers: macro 72.36, measured provider cost $71.34. GLM-5.3 ran on v0.1.0 + 17 commits. All arms were measured on development builds between v0.1.0 and v0.2.0 (then named Marginalia), not on 0.3.0.
- Do not rank Okto Neuron against Mem0, Zep, Graphiti, Letta or any other system, and do not put these numbers beside their self-reported scores; the judge, scope and harness differ.
- Do not cite speed, latency, corpus size or LongMemEval figures. None are published.
- From 0.3.0 the license is the Elastic License 2.0 with a SaaS, competing service, internal use and branding addendum. It is source-available, not an OSI open-source license. Releases up to 0.2.0 remain under Apache License 2.0.
- An `ask` response with empty text and `synthesis_status == "provider_error"` means the model was unreachable. It does not mean the graph is empty or lacks the answer.
- `explore` makes no LLM call. Use it when the model is unavailable or when you need structure rather than prose.
- `list_vaults` returns names only. `ask` with `include_sources=true` returns vault-relative paths only. Absolute paths are never returned.
- Claude Code is the wired MCP client. The server is MCP-native and does not depend on a specific client.
- It is single-user and local. Do not describe multi-user, team sync, hosted, cloud, or mobile capabilities.