Skip to content

About

Production-grade AI agent memory and context management platform (monorepo)

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

58 stars

Watchers

0 watching

Forks

Latest commit

 

History

861 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

IBEX Harness

IBEX Harness

Self-hosted memory and context for multi-tenant AI agents.

Point your agent at an OpenAI-compatible endpoint or add the MCP server, and IBEX resolves tenant and agent identity, injects bounded context, stores governed memories, and attempts best-effort post-response evidence for governed sessions when the PostgreSQL evidence plane is configured.

English · Español · Français · Deutsch · Português (Brasil) · 中文 · العربية

Website · Docs · Status · Benchmarks · Developer guide · Security

CI codecov OpenSSF Scorecard OpenSSF Best Practices License: MIT

Why IBEX

Most agent stacks treat memory as a vector database and identity as an afterthought. IBEX treats both as governed, tenant-scoped infrastructure.

  • Identity on every call. No org_id is accepted from a URL or browser. AuthService is the authority, and every data path filters explicitly.
  • Bounded context, not a prompt dump. Retrieval, ranking, and packing run under a token budget and a deadline, and degrade to directive-only context rather than blocking the proxy.
  • Evidence after the response, deliberately best-effort. Governed requests attempt an evidence outbox write once the response is sent. The guarantee has a stated boundary; see Status and evidence.
Overview
Overview
Sessions
Sessions
Memories
Memories
Session detail
Session detail

Quick start

The supported deployment is the v1-single-node profile from ADR-0097: one self-hosted Docker Compose project, no hosted offering and no HA topology. Prerequisites are Docker Compose v2 or Podman Compose, GNU Make, and the versions in infra/tool-versions.conf; see TOOLCHAIN.md.

git clone https://github.com/Rick1330/ibex-harness.git
cd ibex-harness
make setup
make check-tools

Generate the profile's secrets, start it, retrieve the one-time admin token, and prove it with an authenticated request:

make v1-secrets
make v1-up
make v1-bootstrap-pat   # print the one-time bootstrap PAT
make v1-smoke           # prove the profile with that PAT

Store the bootstrap PAT in your secret manager and remove infra/compose/v1-single-node/bootstrap/bootstrap.pat after the smoke passes. The order matters: make v1-smoke reads that file to authenticate, and a run without it exits 4 (skip), which the target treats as a failure — so deleting the file first leaves the install unproven.

make v1-up rebuilds the images, waits for every required service, and prints the URL. The first start pulls the embedding model into the tei-cache volume; pre-seed that volume for an offline or bandwidth-limited install. make v1-down stops the profile without deleting volumes.

For a restricted sandbox or Podman machine, export the runtime so every later command sees it:

export IBEX_RUNTIME=podman
IBEX_NETWORK=host make setup   # development-stack overlay; v1-single-node rejects host networking

The scripts read IBEX_RUNTIME per process and default it to auto, which prefers Docker whenever docker info succeeds (infra/scripts/dev-tool.sh). On a host that runs both, prefixing a single command would leave make v1-up and make v1-smoke building and proving the profile on Docker, so export it once per shell instead. Leave IBEX_NETWORK out of the shell environment: v1-single-node refuses host and exits 2, and the switch means something only to the development stack.

make env-doctor diagnoses runtime, port, DNS, and telemetry issues.

Contributor path

The development stack is for working on the code, not for running the supported profile:

make compose-dev-up
make db-migrate
make db-seed

Start AuthService and the proxy in two terminals using the commands in DEVELOPMENT_GUIDE.md §4.4, then run the smoke test:

make dev-smoke

make db-seed is local-development only; never run it against a shared environment.

Run the Console

pnpm install --frozen-lockfile --ignore-scripts
IBEX_OPERATOR_API_ORIGIN=https://operator.example.invalid pnpm --filter @ibex/console dev

Open http://127.0.0.1:3000: a development build shows sample data. Add ?demo=0 to exercise the live path, which needs IBEX_OPERATOR_API_ORIGIN set to a reachable operator API and fails closed without one; a production build never renders sample data.

Services

Service Runtime What it does Status
auth/ Go Token and agent validation, PAT lifecycle, provider-credential metadata Local
proxy/ Go OpenAI-compatible LLM proxy: auth, rate limits, context injection, streaming Local
memory/ Python / FastAPI Tenant-scoped memory writes, semantic search, dedup, conflicts, PII Local
context/ Python / gRPC Budgeted retrieval, ranking, and packing behind a caller-token boundary Provisional
embedder/ Python Embedding contract and backend selection Profile-dependent
api/ Python / FastAPI Management plane: tenants, tokens, providers, policies, operator reads Provisional
worker/ Python / Celery Extraction, erasure, billing rollups, maintenance Mixed
mcp-memory/ Python MCP memory tools over Streamable HTTP Partial
mcp-operator/ Python Read-only operator MCP tools Default-off
relay/ Go Evidence outbox relay daemon Default-off
console/ Nuxt 4 + Nitro Operator application and its server-only BFF Provisional

Status is a one-word signal; the status ledger carries the evidence, the boundary, and the open gaps. The full inventory, shared packages, and local infrastructure are in services/README.md, packages/README.md, and infra/README.md.

Console

The Console is the canonical operator application: a Nuxt 4 server-rendered app with a server-only BFF, covering the memory/context lifecycle — agents, sessions, memories, evidence, directives, policies, trace exploration, platform health, and settings. Incidents, drift, audit, analytics, budgets, providers, MCP tools, and access are a separate platform tier (ADR-0089).

It is read-only by design: /login exchanges a personal access token once for an HttpOnly cookie, and the Console exposes no data mutations. Which surfaces have a live read path, and which are labelled previews, is owned by the surface registry in services/console/shared/operator/surfaces.ts; this README does not restate it. See services/console/README.md.

Security and tenancy

Tenant isolation is defense in depth: PostgreSQL RLS plus explicit org_id filtering on every query, with Redis keys namespaced by org_id. Cross-tenant reads return 404, not 403, to avoid existence leaks.

Report vulnerabilities through the private process in engineering/SECURITY.md, not a public issue.

Status and evidence

IBEX distinguishes shipped, mounted-but-provisional, specified-not-implemented, and deferred. Local routes, schemas, fixtures, and design documents are not deployment evidence.

The authoritative runtime claim is the status ledger. Do not infer hosted readiness, measured SLOs, HA, or restore evidence from this README.

Evidence is best-effort, by design. When the PostgreSQL evidence plane is configured and the session's authoritative evidence-fence version is available, governed chat-completion requests attempt an evidence outbox write after the response; the session does not need to be closed first. Evidence may be withheld when the session or its fence is missing, or lost when persistence fails, the bounded queue is saturated, or the process shuts down before draining. The relay is default-off, so this is not a synchronous durable-before-ack guarantee.

The supported profile has been proven, not accepted. On 2026-11-15 all 13 health-checked v1-single-node containers came up healthy, no application connection used the owner login, and a route-level cross-tenant request was refused. That is a live cross-tenant read plus the integration suites — not a full acceptance suite, and not a two-tenant browser journey.

Documentation

Contributing

Read CONTRIBUTING.md and AGENTS.md. Every commit needs a DCO sign-off (git commit -s), and every pull request must link a tracking issue. Conventional Commits are enforced by CI.

License

MIT

About

Production-grade AI agent memory and context management platform (monorepo)

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

58 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages