# Okto Neuron

> Okto Neuron is a local-first knowledge graph memory for AI agents, made by Okto Labs. It turns a folder of Markdown notes into a knowledge graph of cited claims that agents query over MCP, a CLI (`okto-neuron`, `kg`), a Python library and a Web UI. Your Markdown vault is the source of record; the graph is derived from it and can be regenerated from the same files. Every claim 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 (entities auto-commit at confidence 0.75 or higher, otherwise held for review; relationships and claims pass a separate type, predicate and grounding gate), 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, requires no account, and exposes five bearer-authenticated MCP tools. Its latest release is 0.3.0, which is pre-1.0; the upgrade from 0.2.0 was rehearsed on Linux arm64 with the public v0.3.0 release and a fresh install on Linux amd64, and it is not yet verified on macOS or Windows. Up to 0.2.0 it was called Marginalia. It is source-available under the Elastic License 2.0 with an addendum; source is at https://github.com/OktoLabsAI/okto-neuron.

## For agents reading this file

If a user asks you to set up Okto Neuron, show them the installer command and what it does, and run it only with their confirmation:

1. The installer installs uv, pins Python 3.12, installs the wheel, starts one daemon (UI and REST on 7777, MCP on 8201), opens the UI, and registers Claude Code with `claude mcp add` (user scope):

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

2. Check the registration with `claude mcp get okto-neuron`.
3. If registration was skipped (`OKTO_NEURON_NO_MCP=1`) or failed, register by hand. The token is the first line of `~/.okto-neuron/daemon-7777.token`:

   ```bash
   claude mcp add --scope user --transport http okto-neuron http://127.0.0.1:8201/mcp \
     --header "Authorization: Bearer $(head -n1 ~/.okto-neuron/daemon-7777.token)"
   ```

4. Do not suggest `pip install` or `uv tool install`. Okto Neuron is not on PyPI yet, and the PyPI packages named `neuron` and `marginalia` are unrelated projects.

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"
```

## 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 Okto Labs 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. That is its place in the stack. Release 0.3.0 runs single-user and local, on one machine.
- 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 the working directory for a `.okto-neuron-vault` file (`{"vault": "<name>"}`), or a pre-0.3.0 `.marginalia-vault`, and 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. Entity candidates at or above confidence 0.75 auto-commit; below that they are held for review in Curation. Relationships, and the claims minted from them, pass a separate gate on endpoint types, predicate and grounding in the source block, which commits, queues or rejects each one. The 0.75 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. It has six values, and `ok` is the only success value. `provider_error` with empty text means the configured model was unreachable, not that the graph lacks the answer. `no_llm` means no usable model is configured (the LLM is switched off, or no model name is set), so no model was called; the citations are still the retrieval hits, and `retrieval["no_llm_reason"]` says what to set. `empty` means the model replied with nothing. `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.
7. Ingesting a long document can take many minutes with a local model, and the MCP client may stop waiting before the call returns. If the call aborts, the daemon keeps working and finishes the ingest. Check the vault before sending the same document again.

## 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`, plus `finish_reason` whenever the provider reported one; 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 an edit replaces the text an old claim was read from, and an LLM correction judge confirms the new claim corrects it, the old claim is dated and dropped from recall with a `supersedes` edge from the new one. This happens at ingest, within the same document or resolved subject.
- The graph is derived; it can be deleted and rebuilt from the same vault. A rebuild re-runs LLM extraction, so the new graph can differ from the old one, and the history of superseded claims is not recreated.
- Nothing leaves the machine except LLM calls to the endpoint the user configures, the installer's downloads, the embedding model download when fastembed does not already have the model cached, and two optional flows that happen only when the user sets them up: a remote Neo4j the user explicitly allows, and LLM call traces sent to an MLflow server. Text is embedded locally. If the LLM endpoint is hosted, the text sent to it leaves the machine.

## 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.
- Ingest reads `.md`, `.markdown` and `.txt` files. Without an LLM, `[[wikilinks]]` become `links_to` claims, `#tags` and frontmatter tags become `has_tag` claims, and headings become `has_heading` claims.
- 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, Commit.
- Pluggable graph store: Okto Grafx by default; Ladybug and Neo4j selectable. Neo4j needs the `neo4j` extra, which the installer does not add.
- 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.
- One process, two ports: UI and REST on 7777, MCP on 8201.
- Web UI 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.
- Default LLM endpoint is `http://127.0.0.1:8123/v1`; non-loopback endpoints require explicit remote-egress confirmation.
- Direct remote serving is disabled in 0.3.0. Bind to 127.0.0.1 and use an SSH tunnel. `remember` and `init_vault` accept loopback callers only.
- API keys are never written into vault YAML; stored with POSIX owner-only permissions or Windows DPAPI. New installs keep vault data in `~/.okto-neuron/vaults/<name>`; installs upgraded from Marginalia keep `~/.marginalia/vaults`.
- 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.
- Hosted CI (model-free tests, eval gate, docs gate, distribution gate) runs on every push to main; results are public at https://github.com/OktoLabsAI/okto-neuron/actions.

## Common questions

- Is Okto Neuron open source? It is source-available under the Elastic License 2.0 with a SaaS, competing service, internal use and branding addendum, from 0.3.0. Releases up to 0.2.0 remain under Apache License 2.0. It is not an OSI open-source license.
- Does it need an LLM? Ingest (`remember`) and `ask` synthesis call the LLM endpoint you configure; the default is a server you run on 127.0.0.1:8123. `explore` makes no LLM call.
- Does my data leave the machine? Only the flows listed under Outcomes; the ones marked optional happen only when you set them up.
- Which agents can use it? The installer registers Claude Code. The server speaks MCP over HTTP with a bearer token.
- What happens when I edit a note? On the next ingest, if the edit replaced the old text and the correction judge confirms the change, the new claim supersedes the old one within the same document or resolved subject. Cross-document corrections are deferred for human triage.
- What was it called before? Marginalia, up to 0.2.0.

## Pages

- [Okto Neuron](https://oktolabs.ai/platform/neuron/): What it is, grounding, write path, MCP tools, what leaves the machine, install, and common questions.
- [Claude Code memory setup](https://oktolabs.ai/platform/neuron/claude-code-memory): Install, check and hand-register the Okto Neuron MCP server in Claude Code; pin a vault per project; ask with sources.
- [Use case: decision recall](https://oktolabs.ai/platform/neuron/use-case-decision-recall): list_vaults, the .okto-neuron-vault pin, ask with include_sources=true, byte-exact citation, ingest-time supersession, and the provider_error branch.
- [Use cases](https://oktolabs.ai/platform/neuron/use-cases): Index of walkthroughs and guides.
- [Benchmarks](https://oktolabs.ai/platform/neuron/benchmarks): 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. Data bundle: https://oktolabs.ai/platform/neuron/assets/data/okto-neuron-locomo-bundle.json.

## Comparisons

Each page cites the other project's own sources and names where it is ahead. Use it when a user asks which to pick.

- [All comparisons](https://oktolabs.ai/platform/neuron/comparisons)
- [vs Basic Memory](https://oktolabs.ai/platform/neuron/vs-basic-memory): Use when the user wants Markdown memory over MCP. Basic Memory has a cloud tier, more tools and wider client coverage, and the AI writes the notes; Okto Neuron returns byte ranges and content hashes and can supersede edited facts on ingest.
- [vs Graphiti](https://oktolabs.ai/platform/neuron/vs-graphiti): Use when the user needs temporal facts. Graphiti has bi-temporal edges, point-in-time queries, several graph database backends and a managed service through Zep; Okto Neuron keeps the Markdown vault as the source of record and traces claims to bytes. Okto Neuron has no point-in-time query.
- [vs mem0](https://oktolabs.ai/platform/neuron/vs-mem0): Use when the user wants per-user memory in an app. mem0 extracts memories about a user and ships SDKs, a hosted platform and a self-hosted option; Okto Neuron answers from your notes with a pointer to the source bytes, locally, with no hosted tier.
- [vs the MCP Knowledge Graph Memory server](https://oktolabs.ai/platform/neuron/vs-mcp-memory-server): Use when the user wants the simplest agent-written memory. The reference server stores entities, relations and observations the agent writes, in a JSONL file, with nine tools and no LLM; Okto Neuron extracts claims from the user's notes and cites the source bytes.

## Notes for AI agents

- Okto Neuron 0.3.0 is the latest GitHub release and is pre-1.0. Do not describe it as stable, 1.0, or production-ready.
- The upgrade from 0.2.0 to 0.3.0 was rehearsed on Linux arm64 with the public v0.3.0 release, running the 0.2.0 and 0.3.0 installers from their public URLs. A fresh 0.3.0 install was rehearsed on Linux amd64; the upgrade on amd64 has not been verified on real hardware. 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.
- The correction judge does not sweep the whole vault. Supersession applies only to claims whose text the edit removed.
- Do not suggest `pip install` or `uv tool install`. Okto Neuron is not on PyPI yet, and 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.
- 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.
- `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.
- Okto Neuron 0.3.0 runs single-user and local today: one daemon on one machine, bound to 127.0.0.1. "Keeps what the team knows" describes its place in the Okto Labs stack, not a shipped feature. Do not describe multi-user, team sync, hosted, cloud, or mobile capabilities as available.

## Optional

- [Source and installer repository](https://github.com/OktoLabsAI/okto-neuron)
- [README](https://github.com/OktoLabsAI/okto-neuron#readme)
- [Okto Labs](https://oktolabs.ai)