n3rv
Invisible engineering infrastructure for opencode AI agents: memory, skills, and subagent dispatch, bootstrapped with a single command.
- Source repo
- juanmanueldaza/n3rv
- Stars
- ★ 10
- Last updated
- 24d ago
- License
- Apache-2.0
- Primary language
- Python
- FA score
- 57/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformOpenAI API
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- opencode users who want to scaffold a complete workspace (AGENTS.md, skills, plugins, git hooks) for a new project in one command
- Not a fit if
- Teams that want a hosted, turnkey agent and do not use opencode
- Users with no DashScope/OpenAI keys and no capacity to run local Ollama/vLLM models
- Source review
- 57/100 · Major gaps
What does this agent do, and when should you use it?
n3rv is a runtime library and config generator for opencode agent workspaces, maintained by Juan Manuel Daza. Running `n3rv init` generates AGENTS.md, opencode., skill/command/plugin directories, and `.n3rv/` memory and hub configuration. Runtime capabilities include a provider abstraction (Qwen/DashScope, OpenAI, local Ollama/vLLM), an HTTP-based A2A hub for cross-process task delegation, and MAGI dual-store memory (ChromaDB vector search plus SQLite relations). It also ships two MCP stdio servers, `n3rv-memory` and `n3rv-hub`, consumable by any MCP client. Licensed under Apache-2.0, it positions itself as the implementation counterpart to the satellite protocol specs in the companion repo `reverberage/hub`.
After installation, n3rv init uses Jinja2 templates to generate AGENTS.md, opencode., .opencode/ (skills, agents, commands, plugins), .n3rv/ (memory, hub config), and .githooks/ in your project. At runtime, the ModelProvider Protocol and get_provider() factory resolve the LLM backend from the N3RV_PROVIDER environment variable (qwen/openai/local), so satellites never hardcode model IDs or API keys. The A2A hub, started with n3rv hub start, listens on 127.0.0.1:19820, routes cross-process agent tasks by skill_id, and persists results to JSON files. MAGI memory writes SDD artifacts, session summaries, and agent verdicts into ChromaDB (semantic search) and SQLite (relations), manageable via n3rv memory list|search|prune|stats. The MCP servers n3rv-memory and n3rv-hub expose memory operations and task delegation over stdio. n3rv daemon manages a background daemon, and n3rv org manages multi-project workspaces with shared skills and GitHub branch protection.
- opencode users who want to scaffold a complete workspace (AGENTS.md, skills, plugins, git hooks) for a new project in one command
- Teams delegating tasks across multiple opencode processes via the A2A hub, routed by skill_id
- Developers who want long-term semantic memory for agents, retrieving past session summaries and verdicts from ChromaDB
- Qwen-on-DashScope users who want satellites to resolve providers at runtime without hardcoding model IDs or keys
- MCP client users who want stdio access to memory retrieval or task delegation
- Organizations maintaining multiple repos that want shared skills and automated GitHub branch protection
How do you install or deploy this agent?
Install directly from GitHub with pip, then initialize inside your project:
bash
pip install git+https://github.com/juanmanueldaza/n3rv.gitTo run the test suite, install dev dependencies:
bash
pip install -e ".[dev]"pytest
How do you use this agent?
Initialize a workspace in your project directory (optionally choosing a stack):
bash
cd your-project
n3rv init [--stack python|node|go|generic] [--force]Set the required environment variables (default provider is qwen):
bash
export DASHSCOPE_API_KEY=...
export N3RV_PROVIDER=qwen
export N3RV_DEFAULT_MODEL=qwen3-coder-plusStart the A2A hub, manage the daemon and memory:
bash
n3rv hub start
n3rv daemon install|start|stop|status|enable|logs
n3rv memory list|search|prune|stats
n3rv org init|list|add|remove|protectWhat are this agent's strengths and limitations?
- A single
n3rv initgenerates a complete opencode workspace (AGENTS.md, skills, plugins, git hooks), eliminating manual setup - Provider abstraction supports Qwen, OpenAI, and local Ollama/vLLM, with runtime resolution preventing vendor lock-in
- A2A hub provides HTTP-based cross-process agent task delegation routed by skill_id with JSON persistence
- MAGI dual-store memory combines ChromaDB semantic search with SQLite relations for session summaries and verdicts
- Built-in MCP stdio servers (n3rv-memory, n3rv-hub) are reusable by any MCP client
- Core workflow targets the opencode ecosystem; teams not using opencode must assess adaptation costs of the generated configs
- Defaults depend on DashScope/Qwen (including a specific default base URL); switching providers requires understanding the env-var system
- MAGI memory requires maintaining dual ChromaDB and SQLite stores, adding runtime and data-management overhead
- Beyond the README there is no standalone deployment documentation or release notes, so deep integration requires reading the code
- The upstream repo (juanmanueldaza/n3rv) is GPL-2.0 while this repo is Apache-2.0; the license difference warrants legal confirmation
How does this agent compare with similar options?
The README explicitly divides work with the companion repo reverberage/hub: hub ships the satellite protocol, specs, and scaffold scripts (contracts), while n3rv ships the runtime engine (providers, A2A hub, memory, daemon, CLI, init). Both are Apache-2.0.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| n3rv This agent | 57 · Major gaps | CLIFree + model costs | ★ 10 | 24d ago | Python | OpenAI API |
| FastAgent | 46 · Major gaps | CLIFree + model costs | ★ 3.9k | today | Python | Codex · OpenAI API · Claude API |
| Compartment | 76 · Good | CLIFree | ★ 581 | 5d ago | Python | Codex · Claude Code |
| Claude-Mem | 73 · Some gaps | CLIFreemium | ★ 95k | 1d ago | TypeScript | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows a concrete, checkable CVE mitigation argument for ChromaDB CVE-2026-45829 in pyproject.toml (PersistentClient only, no HTTP server, no trust_remote_code) and least-privilege CI permissions (contents: read) — strengths. Deductions: the n3rv-exec executable MCP server entry point exists in pyproject but its source is not in evidence, so least privilege for it cannot be verified; init generates git hooks, installs a daemon, and can set GitHub branch protection — external side effects lacking per-step user confirmation beyond --force/--dry-run; update has --dry-run but no documented rollback path; data residency and cleanup details are undocumented. API keys flow via documented env vars; no hardcoded credentials found.
Tests corroborate README claims (agent cards, hub RPC, task recovery, RESTART_RECOVERY error codes), dependencies carry minimum-version floors, and CI covers Python 3.11–3.13. Deductions: no lockfile evidence, so dependency availability rests upstream; failure-message coverage is only inferable from tests since src is absent; the mypy CI step tolerates failure with '|| true', weakening type-check credibility.
README clearly targets opencode developers, supports multiple stacks (python/node/go/generic), and delineates boundaries ('It is NOT a satellite') plus the hub/n3rv division of labor. Deductions: trigger precision for skills and skill_id routing lacks documented matching rules; the default DashScope international endpoint imposes unaddressed adaptation cost for other users.
Architecture is well documented: clear README structure, hub/n3rv relation table, env-var table, SECURITY.md with response timelines and reporting channels, named maintainers, and proactive disclosure of the upstream GPL-2.0 relationship. Deductions: no CHANGELOG file (only a releases link); no FAQ; only one Quick Start example; version 0.1.1 alpha implies unstable naming/interfaces; the stated 'Upstream is GPL-2.0' vs this repo's Apache-2.0 licensing lineage is disclosed but unexplained.
Generated artifacts (AGENTS.md, opencode., .opencode/, .n3rv/) are explicitly listed, making output usability assessable; the memory + hub + provider abstraction offers differentiated value for the opencode ecosystem, backed by tests covering agent cards and task delegation. Deductions: a heavy dependency stack (chromadb, onnxruntime, aiohttp) is costly for an alpha tool, and the headline value claim ('Invisible engineering infrastructure') lacks quantified or comparative support.
The CVE citation in pyproject (ID, blast radius, mitigation conditions) is independently checkable, and tests corroborate README functional claims (card sets, recovery state transitions). Deductions: implementation source for n3rv-code-graph and n3rv-exec entry points is absent from evidence, so their existence and safety are unverifiable; marketing phrasing ('Invisible', 'Satellites use it at runtime') is not separated from verifiable facts; no execution evidence — all judgments are static readings.
- n3rv-exec is a declared executable MCP server entry point, but its source is not in the provided evidence; review its command-execution surface before installing.
- n3rv init writes git hooks and can install a system daemon and alter GitHub branch protection — external side effects; run it in an isolated environment and inspect generated files first.
- The ChromaDB CVE mitigation rests on the static claim that only PersistentClient is used; re-evaluate before upgrading or switching to HTTP mode.
- Upstream is stated as GPL-2.0 while this repo is Apache-2.0; the licensing lineage is unexplained — clarify before commercial use.
- Project is at 0.1.1 alpha with no CHANGELOG; interfaces and naming may change, so upgrade with care.
- Publisher is not verified by the curated enterprise registry; treat identity as unknown.
FAQ
Does running n3rv cost money?
Do I have to use opencode?
What are the default provider and model?
qwen, the default model ID is qwen3-coder-plus, and the default base URL points to the DashScope international compatible endpoint; override via N3RV_PROVIDER, N3RV_DEFAULT_MODEL, and related environment variables.How does the A2A hub work?
n3rv hub start, it listens on 127.0.0.1:19820, routes cross-process agent tasks by skill_id, and persists results to JSON files.