Files you own. Memory your agents can trust.

NexusOS

NexusOS is a local-first knowledge operating system for AI agents. It turns ordinary
folders of Markdown and text files into a structured, searchable memory layer exposed
through a CLI and Model Context Protocol server.

Your source files remain the system of record. NexusOS builds disposable derived state
inside .nexusos/, then gives humans and agents deterministic tools to search, browse,
read, inspect links, assemble context, and verify workspace health.

[!IMPORTANT]
NexusOS v0.1.0 is the first stable release. The planned v0.1 core feature
scope, release hardening, packaging validation, cross-platform proof,
security review, and public contract freeze are complete. See the
release roadmap.

Why NexusOS

Agent memory should not require surrendering your notes to a proprietary database or
trusting an opaque retrieval pipeline.

NexusOS is built around a smaller contract:

• Local first: core workflows require no hosted account or network connection.
• Files stay yours: Markdown and text remain readable without NexusOS.
• Deterministic retrieval: SQLite FTS5, stable IDs, source paths, and line ranges make
  results inspectable.
• Agent native: the same service layer powers the CLI and MCP tools.
• Read-only by default: retrieval never edits source documents.
• Rebuildable state: the index can be deleted and regenerated from source files.

Where NexusOS fits

NexusOS is not designed as a self-evolving agent-memory system. It is a source-grounded
knowledge substrate: your files remain canonical while NexusOS builds deterministic,
rebuildable retrieval state around them.

This is qualitative architectural positioning, not a benchmark or ranking.

The key distinction is authority: NexusOS protects and exposes canonical knowledge,
while evolving memory systems may create, update, consolidate, or rewrite memory
representations over time.

What works today

v0.1.0 includes:

• safe workspace initialization with blank and starter templates
• path boundaries, deny paths, nested-workspace protection, and doctor checks
• deterministic Markdown and plain-text indexing into SQLite with FTS5
• incremental indexing and content-aware stale-index detection
• ranked search with source paths, headings, snippets, and line ranges
• browse, read, recent, links, and deterministic context navigation
• workspace linting for link, frontmatter, structure, and staleness problems
• MCP over stdio and loopback-first Streamable HTTP
• a read-only local inspection API and bundled UI
• JSON output for automation-friendly command paths

Not included in v0.1: embeddings, vector search, ingestion connectors, guarded source
writes, cloud hosting, OAuth, sync, or multi-user collaboration.

Quick start

Install the stable release from PyPI (full instructions: docs/install.md):

pip install nexusos

nexusos version
nexusos init ./example-workspace
nexusos doctor --workspace ./example-workspace
nexusos index --workspace ./example-workspace
nexusos status --workspace ./example-workspace
nexusos browse --workspace ./example-workspace
nexusos search "workspace" --workspace ./example-workspace

For a disposable end-to-end walkthrough:

nexusos demo

For development from source:

git clone https://github.com/asimons81/nexusos.git
cd nexusos
uv sync
uv run nexusos version

How it works

Markdown and text files
          │
          ▼
  discovery + parsing
          │
          ▼
 deterministic SQLite index
          │
          ├── CLI search and navigation
          ├── workspace linting
          ├── local inspection API and UI
          └── MCP tools for agents

The index is derived state. Source documents are never converted into a proprietary
format and can be recovered without NexusOS because they never left the filesystem.

CLI

Use nexusos COMMAND --help for the current option contract. Workspace commands detect
the current workspace unless --workspace is supplied.

The CLI commands, options, exit codes, configuration keys/environment variables, JSON
shapes, and MCP tool schemas are frozen for the v0.1 train and inventoried in
docs/contracts.md. tests/contracts/ locks the surface; changes
require a deliberate roadmap decision and changelog entry.

MCP for agents

Start NexusOS as a stdio MCP server:

nexusos mcp --workspace /path/to/workspace

Generic client configuration:

{
  "mcpServers": {
    "nexusos": {
      "command": "nexusos",
      "args": ["mcp", "--workspace", "/path/to/workspace"]
    }
  }
}

Available tools:

All retrieval tools are read-only. index writes only disposable derived state.

MCP Streamable HTTP is loopback-first but unauthenticated. Do not expose it directly to
an untrusted network. See docs/mcp.md and SECURITY.md.

Workspace layout

A starter workspace uses a practical folder convention, not a proprietary storage
format:

workspace/
├── nexusos.toml
├── README.md
├── SCHEMA.md
├── inbox/
├── raw/
│   ├── articles/
│   ├── conversations/
│   ├── notes/
│   └── transcripts/
├── wiki/
│   ├── concepts/
│   ├── entities/
│   ├── projects/
│   ├── queries/
│   └── _archive/
├── ops/
│   ├── decisions/
│   ├── sops/
│   └── workflows/
├── mocs/
├── journal/
└── .nexusos/          # generated state, safe to rebuild

Collections and file patterns are configurable in nexusos.toml.

Safety boundary

NexusOS v0.1 is designed for a local, single-user workspace controlled by the operator.

The current contract includes:

• no source-document mutation during indexing, retrieval, linting, or MCP reads
• denied-path and workspace-boundary validation
• nested-workspace prevention
• transactional index writes and an exclusive writer lock
• temporary-file hardening for critical state writes
• loopback defaults for local HTTP transports
• Host validation, Origin checks, and a per-process token for the inspection API

The inspection API and MCP Streamable HTTP are separate surfaces with different security
contracts. The inspection API is token-protected and warns on a non-loopback bind; MCP
Streamable HTTP is unauthenticated and refuses a non-loopback bind unless the operator
explicitly opts in with --allow-non-loopback / NEXUSOS_ALLOW_NON_LOOPBACK=1. A
non-loopback bind is not a claim that NexusOS is an internet-facing authenticated
service.

Review SECURITY.md and the active hardening work in
ROADMAP.md before using NexusOS outside the supported local boundary.

Configuration

Workspaces are configured through nexusos.toml. Effective values are resolved in this
order, with later layers overriding earlier ones:

1. built-in defaults
2. nexusos.toml
3. NEXUSOS_* environment variables
4. CLI flags where supported

nexusos config show
nexusos config show --effective
nexusos config show --json

See docs/configuration.md for valid keys, defaults, environment
variable names, and current limitations.

Development

uv sync
uv run ruff check .
uv run ruff format --check .
uv run mypy src
uv run pytest -q --cov=nexusos
uv run nexusos version

Coverage is enforced: the aggregate gate is 80% ([tool.coverage.report] fail_under),
and security-critical modules (core/path_safety.py, indexing/lock.py,
services/serve_service.py, mcp/) keep targeted floors in CI. The full test
suite (unit + integration + security) must pass on every supported platform
before release.

Read these before changing the repository:

• AGENTS.md: non-negotiable constraints and task protocol for coding agents
• CONTRIBUTING.md: contributor setup and pull-request expectations
• docs/architecture.md: dependency direction and system contracts
• ROADMAP.md: versioned release tasks and acceptance gates
• docs/releasing.md: release procedure and evidence checklist

Agent execution contract

Roadmap work should reference a task ID such as A3-04 or RC-03. Agents must:

1. state the task and acceptance criteria they are implementing
2. inspect implementation and tests before editing behavior or docs
3. preserve architecture boundaries and source immutability
4. add or update tests for behavioral changes
5. run the complete verification gate
6. update affected docs and changelog entries in the same change
7. report evidence, limitations, and deferred work explicitly

“Implemented” without verification evidence is not a completed roadmap task.

Documentation

Release status

The repository has completed the alpha and release-candidate train and is shipping
v0.1.0 as the first stable release. The full-suite platform matrix, measured
coverage policy, signed-tag gate, and package verification are in place.

Follow progress in ROADMAP.md.

License

Apache-2.0. See LICENSE.