AI's memory. On your machine, under your control

Uh oh!

There was an error while loading. Please reload this page.

Notifications You must be signed in to change notification settings

Fork 10

Star 140

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

9 Commits

9 Commits

.github

.github

apps

apps

bin

bin

docs

docs

pi-package

pi-package

runtime

runtime

scripts

scripts

.env.example

.env.example

.gitattributes

.gitattributes

.gitignore

.gitignore

CHANGELOG.md

CHANGELOG.md

CITATION.cff

CITATION.cff

LICENSE

LICENSE

README.md

README.md

package-lock.json

package-lock.json

package.json

package.json

Repository files navigation

Your AI's memory. On your machine, under your control.

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.

Why exxperts

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.

One product, two surfaces

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.

Product capabilities

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.

Quick start

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.

Updating

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 quickstart

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 through bash.exe, which is discovered automatically in the standard Git for Windows install location (C:\Program Files\Git\bin\bash.exe) or on PATH.

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.

What to install for full functionality

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 during npm install; lets rooms visually review the HTML decks they author and read JavaScript-rendered pages. If the download couldn't run, enable it later with npx playwright install chromium (or skip it during install with EXXETA_SKIP_BROWSER_INSTALL=1 npm install).

Web search: a container engine plus a one-time setup command. See Web search (optional).

Model authentication: provider sign-in or API keys. See Model/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 ; 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 (optional)

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.

Model/provider setup

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.

Develop from the repo

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.

Current limitations

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.

More docs

docs/README.md: canonical documentation index with audience and status labels.

docs/quickstart.md: install, connect, first room, first memory.

docs/how-exxperts-works.md: what the product is and how the pieces fit.

docs/developer.md: developer architecture and repo guide.

docs/web-search.md: web search setup and operations.

docs/mcp.md: MCP connectors, with transports, config locations, and commands.

docs/packaging-local.md: local npm package validation.

CHANGELOG.md: public-facing changelog.

Team

exxperts is designed and built by Borja Odriozola Schick (@borcho23) and Fernando Pastor Alonso (@ferpastoralonso) at Exxeta, fr

[truncated for AI cost control]