exxperts gives you persistent AI rooms with governed, approval-gated memory: agents that remember you and your work across sessions, with every memory write approved by you. Everything runs and stays local: rooms, memory, knowledge base, artifacts, and usage data are files on your disk.
Memory you govern. Rooms remember decisions, preferences, and context across sessions, but every memory write goes through an approval gate you control. No silent profile-building.Local-first, verifiably. Rooms, memories, knowledge base, artifacts, and token usage live as plain files under~/.exxperts
. You can read, back up, or delete all of it. There is no telemetry: the only network traffic is what you use, meaning calls to your model provider, web research if you enable it, and any MCP connectors you add.An agentic runtime, not a chat wrapper. Rooms use curated tools (knowledge base, artifacts, local web research, MCP connectors) under a permission model scoped to each surface. Rooms never get an unrestricted shell.One product, two surfaces. The web app and the CLI/TUI share the same rooms, memory, and credential store; switch between them freely.
If you know Open WebUI or AnythingLLM: those are excellent local chat/RAG frontends. exxperts is a different shape: a local agentic runtime focused on persistent, governed memory and auditable agent behaviour, not chat over your documents.
| Surface | Launch | What you get |
|---|---|---|
| Web app | ||
exxperts web |
||
| Rooms with memory, KB, artifacts, web research, approvals, and the wallet. | ||
| CLI / TUI | ||
exxperts cli |
||
| The same rooms in your terminal, run from the folder you want as the workspace. |
The web app is the full product: AI setup, memory review and approvals, the wallet, connectors, and skills all live there. The CLI/TUI focuses on the rooms themselves. Bare exxperts
opens a picker for the two surfaces (web app recommended). Product/app state stays local under ~/.exxperts/app
(%USERPROFILE%\.exxperts
on Windows); embedded runtime provider/auth/model/session state lives under ~/.exxperts/agent
.
-
Local web workspace with landing page, persistent rooms, approvals, and wallet.
-
Rooms-only CLI/TUI sharing the same room runtime and governance.
-
User-created skills from the web UI.
-
Approval-gated memory, KB writes, and Markdown/HTML artifacts.
-
Markdown/Obsidian KB tools and local web search.
-
MCP connectors on web and CLI through a single proxy tool. Bring your own servers; see .
docs/mcp.md -
Local token/cost wallet from
~/.exxperts/app/usage.jsonl
.
Prerequisites: Node.js 20.6+ and npm. On Windows, apply the two Git settings from the Windows quickstart before cloning.
git clone https://github.com/EXXETA/exxperts.git
cd exxperts
npm install
npm run install:global # builds, packs, and installs the exxperts commands (all platforms)
Two things to expect: npm install
also fetches headless Chromium (~150 MB, one-time; skip it with EXXETA_SKIP_BROWSER_INSTALL=1 npm install
), and install:global
builds the whole app before installing @exxeta/exxperts-app
into your global npm prefix, so give it a few minutes.
Then, from any shell:
exxperts web # the web app: rooms, memory, wallet (current folder does not matter)
cd /path/to/your/project
exxperts cli # the same rooms in your terminal, with this folder as the workspace
First run: open AI setup in the web app and sign in to your provider (Claude and ChatGPT subscriptions sign in with one click; API keys and OpenAI-compatible gateways also work; see Model/provider setup). Something not working? npm run doctor
from the repo root checks every layer and prints the fix.
New here? docs/quickstart.md walks the whole path in about five minutes: install, connect your AI, first room, first memory. For an orientation on what the product is and how the pieces fit, read
docs/how-exxperts-works.md
Same on every platform, from the repo folder:
git pull
npm install # in case dependencies changed
npm run install:global # rebuilds and reinstalls the global commands
The global exxperts
commands then run the new version. If anything misbehaves after an update, or anytime, run npm run doctor
from the repo folder. Developing from the clone instead of the global install? Update with git pull && npm install && npm run build
.
Windows is supported for both the web app and the CLI/TUI. Requirements:
Git for Windows ≥ 2.40(https://gitforwindows.org).** Git Bash is required**: the agent's shell tool runs commands throughbash.exe
, which is discovered automatically in the standard Git for Windows install location (C:\Program Files\Git\bin\bash.exe
) or onPATH
.Node.js 20.6+ (LTS recommended) and npm(https://nodejs.org).** Windows Terminal**recommended for the CLI/TUI (legacy conhost is untested).
One-time Git settings before cloning (long paths matter because node_modules
trees exceed the 260-character MAX_PATH
):
git config --global core.longpaths true
git config --global core.autocrlf false # the repo's .gitattributes manages line endings
Then install from PowerShell or Git Bash, with the same commands as everywhere else:
git clone https://github.com/EXXETA/exxperts.git
cd exxperts
npm install
npm run install:global
And run from any shell:
exxperts web # web app
exxperts cli # CLI/TUI, run from the folder you want as workspace
Web search works on Windows too: install Docker Desktop, then run node scripts\searxng.mjs start
once from any shell. See docs/web-search.md.
Developing from the clone without a global install? Use the shell-independent forms: node bin\exxperts-web.cjs
, node bin\exxperts-cli.cjs
, and node scripts\exxeta-web.mjs
(dev web app with server + Vite UI). The bash launchers in scripts/
also work from Git Bash.
Everything runs locally. Full functionality is four layers; only the first is required:
Core app: Node.js 20.6+ and npm, then the quick-start steps above.** Headless Chromium (~150 MB, one-time)**: downloaded automatically duringnpm install
; lets rooms visually review the HTML decks they author and read JavaScript-rendered pages. If the download couldn't run, enable it later withnpx playwright install chromium
(or skip it during install withEXXETA_SKIP_BROWSER_INSTALL=1 npm install
).Web search: a container engine plus a one-time setup command. SeeWeb search (optional).** Model authentication**: provider sign-in or API keys. SeeModel/provider setup.
Verify any setup with npm run doctor from the repo root: it checks all of the above, plus MCP config and that outbound web fetches decode cleanly (corporate TLS-inspection proxies can corrupt responses), and prints the fix for anything missing.
install:global
wraps npm run build && npm pack && npm install -g <tarball>
; the manual steps and one-off runs via npm exec
(no global install) are documented in docs/packaging-local.md. If macOS returns
EACCES
, use a user-level npm prefix instead of sudo
; that is also covered there. If a newer npm warns that install scripts were blocked (allow-scripts
), the app still works. The blocked steps are the Chromium download (recoverable anytime with npx playwright install chromium
) and cosmetic MCP page branding.Web search ships disabled and runs fully locally through a SearXNG container: no API key, no third-party search SaaS. Note: your search queries still go to public search engines, so avoid searching confidential client or internal content.
To enable: install Docker Desktop or (lighter on macOS) OrbStack, then from the repo directory run the one-time setup command and restart the app:
./scripts/searxng start # macOS / Linux / Git Bash
node scripts\searxng.mjs start # Windows (PowerShell or cmd)
Setup details, keeping it running across reboots, status/stop commands, and Windows notes: docs/web-search.md.
Rooms need a signed-in model provider before they can respond. Pick whichever path fits.
For subscription providers (Claude, ChatGPT Plus/Pro), launch the web app, open AI setup, and use the Sign in → button on the provider's profile card. The provider login opens in the browser, and credentials stay in the local credential store.
For an OpenAI-compatible gateway (a company LiteLLM or vLLM proxy, for example), everything happens in the web app: open AI setup → Add another provider → Set up gateway, enter the base URL and the model ids your gateway routes, pick the Learn/Review Memory model, then paste your token on the gateway's profile row. The terminal wizard still works if you prefer it:
exxperts web
exxperts setup openai-compatible
When running from a repo clone, use the matching dev setup command instead of any globally installed command:
./scripts/exxperts-web
./scripts/exxperts-cli setup openai-compatible
Any other provider the runtime knows (Google Gemini, Groq, Mistral, DeepSeek, OpenRouter, xAI, and ~25 more) can be added from the web app: open AI setup and use Add another provider, then sign in with a subscription where the provider offers one, or paste an API key. After signing in, approve the models that provider may use: the models available in rooms, plus the one that runs Learn and Review Memory (a default is suggested). Approval creates the provider's AI profile; without it, the provider is signed in but not usable in rooms.
Provider API keys in your shell or repo .env
also work when running from the clone:
OPENAI_API_KEY=...
ANTHROPIC_API_KEY=...
Subscription/OAuth login also works from the terminal: run exxperts cli
, then type /login
. It offers the same provider list as the web app, including API-key entry. The web app and CLI/TUI share the same local runtime credential store, so either path signs in both. Approving models for a newly added provider happens in the web app's AI setup.
npm install
npm run build
npm run doctor # verify the setup
./scripts/exxperts-web # dev web app from this clone
./scripts/exxperts-cli # dev Exxperts CLI/TUI from this clone
Packaging does not change normal development. Keep using the repo scripts while editing code; repack/reinstall (npm run install:global
) only to validate installed-product behaviour. On Windows, use the node
equivalents from the Windows quickstart.
- Distributed as an npm package built from the repo; no native installer yet.
- No hosted multi-user/SSO/RBAC version yet; exxperts is a single-user, local product today.
: canonical documentation index with audience and status labels.docs/README.md
: install, connect, first room, first memory.docs/quickstart.md
: what the product is and how the pieces fit.docs/how-exxperts-works.md
: developer architecture and repo guide.docs/developer.md
: web search setup and operations.docs/web-search.md
: MCP connectors, with transports, config locations, and commands.docs/mcp.md
: local npm package validation.docs/packaging-local.md
: public-facing changelog.CHANGELOG.md
exxperts is designed and built by Borja Odriozola Schick (@borcho23) and Fernando Pastor Alonso (@ferpastoralonso) at Exxeta, from the memory-engine architecture at its core to the product around it.
exxperts is built on Pi by Mario Zechner.
Contact: borja.odriozola.schick@exxeta.ch · fernando.pastor@exxeta.ch
Issues and pull requests are welcome. Before reporting a problem, run npm run doctor
from the repo root and include its output; it often names the fix. For an orientation to the codebase, start with docs/developer.md.
exxperts is source-available under the PolyForm Noncommercial License 1.0.0: free to use, modify, and redistribute for any noncommercial purpose. Commercial use requires a separate license; contact Exxeta.
The bundled runtime under runtime/
is derived from the open-source Pi project (v0.70.5, MIT); the upstream license is preserved in runtime/LICENSE and the fork is documented in
runtime/NOTICE.md
Third-party product names and logos in the connector directory are trademarks of their respective owners (glyphs from Simple Icons, CC0), used for identification only and not covered by this repository's licence.