{"id":46802035,"url":"https://github.com/nexi-lab/nexus","last_synced_at":"2026-04-24T08:01:43.349Z","repository":{"id":318819644,"uuid":"1071945250","full_name":"nexi-lab/nexus","owner":"nexi-lab","description":"Nexus, the shared heartbeat where every agent and human connect, collaborate, and evolve together.","archived":false,"fork":false,"pushed_at":"2026-04-18T11:13:57.000Z","size":69114,"stargazers_count":343,"open_issues_count":65,"forks_count":8,"subscribers_count":5,"default_branch":"develop","last_synced_at":"2026-04-18T13:14:23.378Z","etag":null,"topics":["ai-memory","context-engineering","context-store","filesystem","llm"],"latest_commit_sha":null,"homepage":"https://nexi-lab.github.io/nexus/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nexi-lab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/contributing/build-performance.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-08T03:34:11.000Z","updated_at":"2026-04-18T08:39:55.000Z","dependencies_parsed_at":"2025-10-30T02:25:24.705Z","dependency_job_id":null,"html_url":"https://github.com/nexi-lab/nexus","commit_stats":null,"previous_names":["nexi-lab/nexus"],"tags_count":63,"template":false,"template_full_name":null,"purl":"pkg:github/nexi-lab/nexus","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nexi-lab%2Fnexus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nexi-lab%2Fnexus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nexi-lab%2Fnexus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nexi-lab%2Fnexus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nexi-lab","download_url":"https://codeload.github.com/nexi-lab/nexus/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nexi-lab%2Fnexus/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32168294,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-23T02:19:40.750Z","status":"ssl_error","status_checked_at":"2026-04-23T02:17:55.737Z","response_time":53,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-memory","context-engineering","context-store","filesystem","llm"],"created_at":"2026-03-10T06:04:00.734Z","updated_at":"2026-04-24T08:01:43.343Z","avatar_url":"https://github.com/nexi-lab.png","language":"Python","readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets/logo.png\"\u003e\n  \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"assets/logo.png\"\u003e\n  \u003cimg alt=\"Nexus\" src=\"assets/logo.png\" width=\"180\"\u003e\n\u003c/picture\u003e\n\n### The filesystem \u0026 context plane for AI agents\n\nGive every agent one place to read, write, search, remember, and collaborate — from a single-file script to a fleet of thousands.\n\n[![CI](https://github.com/nexi-lab/nexus/actions/workflows/test.yml/badge.svg)](https://github.com/nexi-lab/nexus/actions/workflows/test.yml)\n[![PyPI](https://img.shields.io/pypi/v/nexus-ai-fs?color=blue)](https://pypi.org/project/nexus-ai-fs/)\n[![nexus-fs](https://img.shields.io/pypi/v/nexus-fs?label=nexus-fs\u0026color=blue)](https://pypi.org/project/nexus-fs/)\n[![@nexus-ai-fs/tui](https://img.shields.io/npm/v/@nexus-ai-fs/tui?label=@nexus-ai-fs/tui\u0026color=blue)](https://www.npmjs.com/package/@nexus-ai-fs/tui)\n[![Python 3.12+](https://img.shields.io/badge/python-3.12+-3776AB?logo=python\u0026logoColor=white)](https://www.python.org/downloads/)\n[![License](https://img.shields.io/badge/license-Apache_2.0-blue)](LICENSE)\n[![Discord](https://img.shields.io/badge/Discord-community-5865F2?logo=discord\u0026logoColor=white)](https://discord.gg/nexus)\n\n[Documentation](https://nexi-lab.github.io/nexus/) · [Quickstart](https://nexi-lab.github.io/nexus/getting-started/quickstart/) · [Examples](examples/) · [PyPI](https://pypi.org/project/nexus-ai-fs/) · [nexus-fs](https://pypi.org/project/nexus-fs/) · [TUI](https://www.npmjs.com/package/@nexus-ai-fs/tui) · [Roadmap](https://github.com/nexi-lab/nexus/issues)\n\n\u003c/div\u003e\n\n---\n\n## Why Nexus\n\nEvery agent framework gives you tool calling. None gives you a shared filesystem. Without one, agents duplicate files, lose context between runs, step on each other's writes, and can't discover what's already been built.\n\nNexus fixes this. One VFS-style interface — start embedded in a single Python process, scale to a daemon-backed deployment with auth, permissions, federation, and multi-tenant isolation. No code changes.\n\n## How it works\n\n```\n┌─────────────────────────────────────────────────────────────────────────┐\n│  BRICKS (runtime-loadable)                                              │\n│  ReBAC · Auth · Agents · Delegation · Search · Memory · Governance      │\n│  Workflows · Pay · MCP · Snapshots · Catalog · Identity · 25+ more      │\n└─────────────────────────────────────────────────────────────────────────┘\n                              ↓ protocol interface\n┌─────────────────────────────────────────────────────────────────────────┐\n│  KERNEL                                                                 │\n│  VFS · Metastore · ObjectStore · Syscall dispatch · Pipes ·             │\n│  Lock manager · Three-phase write (LSM hooks) · CAS dedup              │\n└─────────────────────────────────────────────────────────────────────────┘\n                              ↓ dependency injection\n┌─────────────────────────────────────────────────────────────────────────┐\n│  DRIVERS                                                                │\n│  redb · PostgreSQL (pgvector) · S3 · GCS · Dragonfly · Zoekt · gRPC    │\n└─────────────────────────────────────────────────────────────────────────┘\n```\n\n**Kernel** never changes. **Drivers** swap at config time. **Bricks** mount and unmount at runtime — like `insmod`/`rmmod` for an AI filesystem.\n\n## Requirements\n\n- **Python 3.14+** (Nexus dropped support for 3.12/3.13 in vNEXT). Bare-metal\n  `pip install nexus` requires a Rust toolchain because `pdf-inspector` builds\n  from sdist until upstream ships cp314 wheels. The official Docker image\n  ships Rust and handles this automatically.\n\n## Get started in 30 seconds\n\n### Option A: Docker (recommended)\n\n```bash\npip install nexus-ai-fs                       # CLI + SDK\nnexus init --preset demo                       # writes nexus.yaml + nexus-stack.yml\nnexus up                                       # pulls image, starts Nexus + Postgres + Dragonfly + Zoekt\neval $(nexus env)                              # load connection vars into your shell\n```\n\nOpen `http://localhost:2026`. That's it.\n\n### Option B: Embedded (no Docker)\n\n```bash\npip install nexus-ai-fs\n```\n\n```python\nimport asyncio, nexus\n\nasync def main():\n    nx = await nexus.connect(config={\"data_dir\": \"./my-data\"})\n\n    await nx.write(\"/notes/meeting.md\", b\"# Q3 Planning\\n- Ship Nexus 1.0\")\n    print((await nx.read(\"/notes/meeting.md\")).decode())\n\n    nx.close()\n\nasyncio.run(main())\n```\n\n### Option C: CLI\n\n```bash\nnexus write /hello.txt \"hello world\"\nnexus cat /hello.txt\nnexus ls /\nnexus search query \"hello\" --mode hybrid\nnexus versions history /hello.txt\n```\n\n### Terminal UI\n\nThe TUI is a separate TypeScript package built on OpenTUI:\n\n```bash\nbunx @nexus-ai-fs/tui                                        # published package, connects to localhost:2026\nbunx @nexus-ai-fs/tui --url http://remote:2026 --api-key KEY # connect to remote instance\ncd packages/nexus-api-client \u0026\u0026 npm install \u0026\u0026 npm run build \u0026\u0026 cd -  # build sibling dependency once in a fresh checkout\ncd packages/nexus-tui \u0026\u0026 bun install \u0026\u0026 bun run src/index.tsx          # local development from this repo\n```\n\nFile explorer, API inspector, monitoring dashboard, agent lifecycle management, and more — all from your terminal.\n\n## What you get\n\n| Capability | What it does | How agents use it |\n|---|---|---|\n| **Filesystem** | POSIX-style read/write/mkdir/ls with CAS dedup | Shared workspace — no more temp files |\n| **Versioning** | Every write creates an immutable version | Rollback mistakes, diff changes, audit trails |\n| **Snapshots** | Atomic multi-file transactions | Commit or rollback a batch of changes together |\n| **Search** | Keyword + semantic + hybrid, powered by Zoekt + pgvector | Find anything by content or meaning |\n| **Memory** | Persistent agent memory with consolidation + versioning | Remember across runs and sessions |\n| **Delegation** | SSH-style agent-to-agent permission narrowing | Safely sub-delegate work with scoped access |\n| **ReBAC** | Relationship-based access control (Google Zanzibar model) | Fine-grained per-file, per-agent permissions |\n| **MCP** | Mount external MCP servers, expose Nexus as 30+ MCP tools | Bridge any tool ecosystem |\n| **Workflows** | Trigger → condition → action pipelines | Automate file processing, notifications, etc. |\n| **Governance** | Fraud detection, collusion rings, trust scores | Safety rails for autonomous agent fleets |\n| **Pay** | Credit ledger with reserves, policies, approvals | Metered compute for multi-tenant deployments |\n| **IPC** | Inbox-based inter-agent messaging via pipes | Agents talk to each other without polling |\n| **Federation** | Multi-zone Raft consensus with mTLS TOFU | Span data centers without a central coordinator |\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eAll bricks and system services →\u003c/strong\u003e\u003c/summary\u003e\n\n**Bricks (runtime-loadable):** Access Manifests · Auth (API key, OAuth, mTLS) · Catalog (schema extraction) · Context Manifests · Delegation · Discovery · Identity (DID + credentials) · IPC (pipes) · MCP · Mount · Parsers (50+ formats via pdf-inspector) · Pay · Portability (import/export) · ReBAC · Sandbox (Docker) · Search · Share Links (capability URLs) · Snapshots · Task Manager · TUS Uploads (resumable) · Versioning · Workflows · Workspace\n\n**System services:** Agent Registry · Agent Runtime · Event Bus · Event Log · Namespace · Scheduler (fair-share, priority tiers) · Sync · Lifecycle\n\n\u003c/details\u003e\n\n## Framework integrations\n\nEvery major agent framework works out of the box:\n\n| Framework | What the example shows | Link |\n|---|---|---|\n| **Claude Agent SDK** | ReAct agent with Nexus as tool provider | [examples/claude_agent_sdk/](examples/claude_agent_sdk/) |\n| **OpenAI Agents** | Multi-tenant agents with shared memory | [examples/openai_agents/](examples/openai_agents/) |\n| **LangGraph** | Permission-scoped workflows | [examples/langgraph_integration/](examples/langgraph_integration/) |\n| **CrewAI** | Multi-agent collaboration on shared files | [examples/crewai/](examples/crewai/) |\n| **Google ADK** | Agent Development Kit integration | [examples/google_adk/](examples/google_adk/) |\n| **E2B** | Cloud sandbox execution | [examples/e2b/](examples/e2b/) |\n| **CLI** | 40+ shell demos covering every feature | [examples/cli/](examples/cli/) |\n\n## Deployment options\n\n| Mode | What | Who it's for |\n|---|---|---|\n| **Embedded** | `nexus.connect()` — in-process, zero infrastructure | Scripts, notebooks, single-agent apps |\n| **Shared daemon** | `nexus init --preset shared \u0026\u0026 nexus up` | Teams, multi-agent systems, staging |\n| **Federation** | Multi-zone Raft consensus across data centers | Production fleets, edge deployments |\n\n### `nexus init` presets\n\n| Preset | Services | Auth | Use case |\n|---|---|---|---|\n| `local` | None (embedded) | None | Single-process scripts, notebooks |\n| `shared` | Nexus + Postgres + Dragonfly + Zoekt | Static API key | Team dev, multi-agent staging |\n| `demo` | Same as shared | Database-backed | Demos, seed data, evaluation |\n\n```bash\n# Embedded (no Docker)\nnexus init                                    # writes nexus.yaml for local embedded mode\n\n# Shared daemon\nnexus init --preset shared                    # writes nexus.yaml + nexus-stack.yml\nnexus up                                      # pulls image, starts stack, waits for health\neval $(nexus env)                             # load NEXUS_URL, NEXUS_API_KEY, etc.\n\n# Demo with seed data\nnexus init --preset demo \u0026\u0026 nexus up\n\n# Add optional services\nnexus init --preset shared --with nats --with mcp --with frontend\n\n# GPU acceleration\nnexus init --preset shared --accelerator cuda\n\n# Pin to a specific version\nnexus init --preset shared --image-tag 0.9.4\n\n# Build from local source (for contributors)\nnexus up --build                              # build + tag as nexus:local-{hash}\nnexus up                                      # reuses local build (no pull)\nnexus up --pull                               # discard local build, pull from remote\n\n# Stack lifecycle\nnexus stop                                    # pause containers (fast, no teardown)\nnexus start                                   # resume paused containers (fast)\nnexus down                                    # stop and remove containers\nnexus logs                                    # tail logs\nnexus restart                                 # down + up\nnexus upgrade                                 # pull latest image for your channel\n\n# Environment variables\nnexus env                                     # print export statements for your shell\nnexus env --json                              # machine-readable\nnexus env --dotenv \u003e .env                     # write .env file\nnexus run python my_agent.py                  # run command with env vars injected\n```\n\n### Docker image\n\nPublished to GHCR (multi-arch: amd64 + arm64):\n\n```\nghcr.io/nexi-lab/nexus:stable          # latest release\nghcr.io/nexi-lab/nexus:edge            # latest develop\nghcr.io/nexi-lab/nexus:\u003cversion\u003e       # pinned (e.g. 0.9.3)\nghcr.io/nexi-lab/nexus:stable-cuda     # GPU variant\n```\n\n## Storage architecture\n\nFour pillars, separated by access pattern — not by domain:\n\n| Pillar | Interface | Capability | Required? |\n|---|---|---|---|\n| **Metastore** | `MetastoreABC` | Ordered KV, CAS, prefix scan, optional Raft | Yes — sole kernel init param |\n| **ObjectStore** | `ObjectStoreABC` | Streaming blob I/O, petabyte scale | Mounted dynamically |\n| **RecordStore** | `RecordStoreABC` | Relational ACID, JOINs, vector search | Services only — optional |\n| **CacheStore** | `CacheStoreABC` | Ephemeral KV, pub/sub, TTL | Optional (defaults to null) |\n\nThe kernel starts with just a Metastore. Everything else is layered on without changing a line of kernel code.\n\n### Cold tiering (Issue #3406)\n\nSealed CAS volumes are automatically uploaded to S3/GCS when they go quiet, cutting cold storage costs by ~80%. The local redb index is retained for O(1) lookups; reads use a single HTTP range request.\n\nAdd to your `nexus.yaml`:\n\n```yaml\ntiering:\n  enabled: true\n  quiet_period: 3600          # seconds before a sealed volume is tiered\n  min_volume_size: 104857600  # 100 MB minimum\n  cloud_backend: s3           # or gcs\n  cloud_bucket: my-bucket\n```\n\nFeatures: write-ahead crash recovery, LRU volume cache with burst detection, streaming downloads (no full-volume RAM buffering), automatic rehydration for burst read patterns.\n\n**Credentials**: AWS env vars / `~/.aws/credentials` / IAM role for S3, or Application Default Credentials for GCS.\n\n**`nexus-fs` (slim package)**: Tiering requires `nexus-ai-fs` (full package). The slim `nexus-fs` package excludes `nexus/services/` where the tiering service lives. If using `nexus-fs`, install cloud extras separately: `pip install nexus-fs[s3]` or `nexus-fs[gcs]`.\n\n## Contributing\n\n```bash\ngit clone https://github.com/nexi-lab/nexus.git \u0026\u0026 cd nexus\nuv python install 3.14\nuv sync --extra dev --extra test\nuv run pre-commit install\nuv run pytest tests/\n```\n\nFor semantic search work: `uv sync --extra semantic-search`\n\n**After cloning, pulling, or switching branches that touch `rust/`**, rebuild the Rust extensions:\n\n```bash\njust setup        # rebuild all crates (requires: cargo install just)\njust doctor       # verify the binary matches current source\n```\n\nOr per-crate: `maturin develop --release -m rust/nexus_kernel/Cargo.toml`\n\n\u003e **Why?** `PYTHONPATH=src` only affects pure-Python imports. Native extensions (`nexus_kernel.so`) resolve via site-packages and must be explicitly rebuilt after Rust changes. A stale binary imports silently but fails at runtime with a cryptic `AttributeError`. See [#3712](https://github.com/nexi-lab/nexus/issues/3712).\n\nClaude Code users: see `CLAUDE.md` (local-only, not committed) for the full contributor guide.\n\n## Troubleshooting\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003eModuleNotFoundError: No module named 'nexus'\u003c/code\u003e\u003c/summary\u003e\n\nInstall from PyPI: `pip install nexus-ai-fs`. The package name on PyPI is `nexus-ai-fs`, not `nexus`.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003eAttributeError: 'Kernel' object has no attribute '...'\u003c/code\u003e\u003c/summary\u003e\n\nThe installed `nexus_kernel` binary is stale. Rebuild:\n\n```bash\njust setup\n# or: maturin develop --release -m rust/nexus_kernel/Cargo.toml\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003ematurin develop\u003c/code\u003e fails at the repo root\u003c/summary\u003e\n\nPoint maturin at a crate manifest: `maturin develop --release -m rust/nexus_kernel/Cargo.toml`\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003efaiss-cpu\u003c/code\u003e resolution fails\u003c/summary\u003e\n\nOnly install semantic search extras on platforms with compatible `txtai`/`faiss-cpu` wheels: `pip install \"nexus-ai-fs[semantic-search]\"`\n\n\u003c/details\u003e\n\n## License\n\nApache License 2.0 — see [LICENSE](LICENSE) for details.\n\nBuilt by [Nexi Labs](https://github.com/nexi-lab).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnexi-lab%2Fnexus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnexi-lab%2Fnexus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnexi-lab%2Fnexus/lists"}