{"id":50729098,"url":"https://github.com/moai-team-llc/agenticmind","last_synced_at":"2026-06-10T07:01:26.884Z","repository":{"id":361539743,"uuid":"1254655884","full_name":"Moai-Team-LLC/AgenticMind","owner":"Moai-Team-LLC","description":"Auditable, self-improving knowledge \u0026 memory for AI agents over MCP. Zero-key \u0026 multilingual by default · citation-enforced answers · replayable why-trace · judge-gated compounding loop. Postgres-only. Reference implementation of the Agentic Product Standard.","archived":false,"fork":false,"pushed_at":"2026-06-08T14:00:18.000Z","size":734,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-08T15:27:11.396Z","etag":null,"topics":["agent-memory","ai-agents","knowledge-base","llm","mcp","model-context-protocol","pgvector","postgres","rag","self-hosted","typescript"],"latest_commit_sha":null,"homepage":"https://agenticmind.moaiteam.com","language":"TypeScript","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/Moai-Team-LLC.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":"SUPPORT.md","governance":"GOVERNANCE.md","roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":"CLA.md"}},"created_at":"2026-05-30T21:03:15.000Z","updated_at":"2026-06-08T14:00:53.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Moai-Team-LLC/AgenticMind","commit_stats":null,"previous_names":["alexduchdev/agenticmind","moai-team-llc/agenticmind"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/Moai-Team-LLC/AgenticMind","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Moai-Team-LLC%2FAgenticMind","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Moai-Team-LLC%2FAgenticMind/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Moai-Team-LLC%2FAgenticMind/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Moai-Team-LLC%2FAgenticMind/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Moai-Team-LLC","download_url":"https://codeload.github.com/Moai-Team-LLC/AgenticMind/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Moai-Team-LLC%2FAgenticMind/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34140776,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-10T02:00:07.152Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["agent-memory","ai-agents","knowledge-base","llm","mcp","model-context-protocol","pgvector","postgres","rag","self-hosted","typescript"],"created_at":"2026-06-10T07:01:07.692Z","updated_at":"2026-06-10T07:01:26.867Z","avatar_url":"https://github.com/Moai-Team-LLC.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"assets/agenticmind-logo.png\" alt=\"AgenticMind\" width=\"118\" /\u003e\n\n# AgenticMind\n\n### The auditable, self-improving knowledge \u0026 memory layer for AI agents.\n\nGrounded answers with **provable citations**, a full **why-trace** for every answer,\nand a corpus that **improves itself** — served to any agent over **MCP**.\n**Zero-key, multilingual, and self-hostable on Postgres alone.**\n\n[![CI](https://github.com/Moai-Team-LLC/AgenticMind/actions/workflows/ci.yml/badge.svg)](https://github.com/Moai-Team-LLC/AgenticMind/actions/workflows/ci.yml)\n[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://www.conventionalcommits.org)\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)\n[![Implements: Agentic Product Standard](https://img.shields.io/badge/implements-Agentic%20Product%20Standard-CD7722.svg)](https://github.com/Moai-Team-LLC/agentic-product-standard)\n[![Runtime: Node or Bun](https://img.shields.io/badge/runtime-Node%20or%20Bun-black.svg)](https://nodejs.org)\n[![DB: Postgres + pgvector](https://img.shields.io/badge/db-Postgres%20%2B%20pgvector-336791.svg)](https://github.com/pgvector/pgvector)\n[![Stars](https://img.shields.io/github/stars/Moai-Team-LLC/AgenticMind?style=social)](https://github.com/Moai-Team-LLC/AgenticMind/stargazers)\n\n**[Quickstart](#-quickstart)** · **[See it work](#-see-it-work)** · **[Agent tools](#-agent-surface-mcp)** · **[How it works](#-how-it-works)** · **[Why](#-why-agenticmind)** · **[The Standard ↗](https://github.com/Moai-Team-LLC/agentic-product-standard)**\n\n\u003csub\u003eIf this is useful, a ⭐ helps others find it — and tells us to keep going.\u003c/sub\u003e\n\n\u003c/div\u003e\n\n---\n\n\u003e **Not \"memory storage for an agent.\"** AgenticMind is the substrate an agent points\n\u003e at when it needs answers it can **trust**, a trail it can **audit**, and a knowledge\n\u003e base that **compounds**.\n\nMost agent memory is a vector store with `save()` and `search()`. That buys you fuzzy\nrecall and zero accountability: you can't tell _why_ an answer came back, whether it's\ncurrent, or whether a source even supports it. AgenticMind treats knowledge as a\nfirst-class, auditable, self-improving substrate — and exposes it to any agent over the\nModel Context Protocol.\n\n## ✨ Why AgenticMind\n\n- 📌 **Citation-enforced** — every claim in an answer is keyed to a numbered source. No source, no claim.\n- 🔍 **Fully auditable** — a replayable _why-trace_ for every answer: what was retrieved, ranked, and used.\n- ♻️ **Self-improving** — validated answers are promoted back into the corpus by a judge-gated compounding loop, driven by **programmatic signals** (not human thumbs).\n- 🧩 **Tiered retrieval** — chunks → typed fact cards → knowledge graph; hybrid vector + full-text, recency-aware.\n- 🔐 **Safe by construction** — scoped, least-privilege MCP tokens, fail-closed auth, guardrails on input _and_ output.\n- 🐘 **One datastore** — Postgres + pgvector carries vectors, full-text, the graph (recursive CTE), _and_ the durable queue. No Redis, no Neo4j, no vector-DB sprawl.\n\n## 🔧 How it works\n\n```mermaid\nflowchart TD\n  A[\"🤖 Agent\"] --\u003e|\"MCP request\"| R[\"Tiered retrieval\u003cbr/\u003epgvector + full-text + graph\"]\n  R --\u003e Y[\"Citation-enforced synthesis\"]\n  Y --\u003e|\"grounded answer + [citations]\"| A\n  Y --\u003e T[(\"Replayable why-trace\")]\n  Y --\u003e|\"programmatic signals\"| L[\"Judge-gated compounding loop\"]\n  L --\u003e|\"promotes validated knowledge\"| R\n```\n\nA request comes in over MCP → the engine retrieves across three tiers → synthesises an\nanswer where **every claim cites a source** → logs a replayable trace → and feeds\nprogrammatic signals into a loop that promotes validated knowledge back into the corpus.\n\n## 🎬 See it work\n\nA real `kl_ask_global` call against a corpus seeded with the Agentic Product Standard. The\nquestion deliberately has **two halves** — one the corpus can answer, one it can't:\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"assets/demo.gif\" alt=\"A live kl_ask_global call: a citation-enforced answer that refuses the unsupported half, with a replayable why-trace\" width=\"780\" /\u003e\n\u003c/div\u003e\n\n```jsonc\n// → kl_ask_global\n{ \"question\": \"When should I use a multi-agent architecture instead of a single agent,\n                and what must every agent ship with according to the standard?\" }\n\n// ← response (trimmed)\n{\n  \"answer\": \"The provided sources do not specify when to use a multi-agent architecture\n             versus a single agent. … According to the Agentic Product Standard, every\n             agent must ship with a written Agent Contract [1]. This contract must cover\n             ownership, forbidden actions, acceptance criteria, failure modes, escalation\n             rules, and logging requirements [1].\",\n  \"citations\": [\n    { \"number\": 1, \"title\": \"Agent Contract requirement\",\n      \"materialId\": \"ba44971b-…\", \"score\": 0.46, \"origin\": \"chunk\" }\n  ],\n  \"model\": \"google/gemini-3.1-flash-lite-preview\",\n  \"retrievalMs\": 606, \"generationMs\": 890,\n  \"phases\": [ {\"phase\":\"embed\",\"ms\":552}, {\"phase\":\"retrieve\",\"ms\":37},\n              {\"phase\":\"synth\",\"ms\":890}, {\"phase\":\"output_filter\",\"ms\":2} ],\n  \"telemetryId\": \"cc942e54-…\"\n}\n```\n\n**Look at what *didn't* happen.** The half the corpus couldn't support, the model **refused to\nanswer** — *\"the provided sources do not specify…\"* — instead of fabricating it. The half it\ncould support is keyed to a numbered citation you can open. And every answer comes with a\n**why-trace** (`phases`, `model`, `telemetryId`) you can replay. That's the whole pitch in one\ncall: **no source, no claim — and a receipt for every answer.**\n\n## 🆚 How it's different\n\n|                         | Plain RAG / memory SDKs | AgenticMind                        |\n| ----------------------- | ----------------------- | ---------------------------------- |\n| Grounded answers        | sometimes               | citation-enforced + post-checked   |\n| Why-trace per answer    | ✗                       | full decision trace                |\n| Self-improving corpus   | ✗                       | compounding loop (judge-gated)     |\n| Relational verification | ✗                       | graph module                       |\n| Runs on                 | varies                  | **Postgres + pgvector** (flagship) |\n\n## ✅ Use it when / 🚫 reach for something else when\n\n**Use AgenticMind when:**\n\n- Your agent must answer **from trusted sources**, and every claim needs a citation.\n- You need a **replayable why-trace** and a single `status` (supported / partial /\n  unsupported / conflicted / needs_review) you can **gate** an agent on.\n- Disagreeing or stale sources must be **surfaced**, not silently resolved.\n- You want **governed** self-improvement — not silent autonomous memory mutation.\n- You need **self-hosting** (Postgres-only) and **MCP-native** access (Claude Code,\n  Cursor, LangGraph, OpenAI/Claude Agent SDK, custom agents).\n\n**Reach for something else when:**\n\n- You only need simple personalised **chat memory** (use a memory SDK).\n- You want a **hosted API / no-code UI today** — AgenticMind is self-hosted infra.\n- You need **SSO / SOC2** out of the box (see the security model for what exists).\n- You're optimising for the **fastest prototype**, not accountable production.\n\n## 🛠 Agent surface (MCP)\n\nA **headless** service (`apps/server`) exposes the engine as MCP tools over\nstreamable HTTP, with fail-closed per-token bearer auth (scoped, least-privilege):\n\n| Tool                 | Scope              | Purpose                                                             |\n| -------------------- | ------------------ | ------------------------------------------------------------------- |\n| `kl_search`          | `knowledge:read`   | semantic / keyword passage search                                   |\n| `kl_ask_global`      | `knowledge:read`   | synthesised answer + citations + a gate-able `status` (optional `intent`/`facts`) |\n| `kl_get_material`    | `knowledge:read`   | fetch a material by id                                              |\n| `kl_graph_neighbors` | `knowledge:read`   | related materials via the knowledge graph                           |\n| `kl_ingest`          | `knowledge:write`  | add text (chunked, embedded, distilled into cards, graph-extracted) |\n| `kl_forget`          | `knowledge:admin`  | delete a material + all derived chunks/cards/graph (inverse of ingest) |\n| `kl_signal`          | `knowledge:signal` | emit a programmatic compounding signal on a prior answer            |\n| `mem_recall`         | `memory:read`      | recall beliefs (private ∪ shared); semantic or `asOf` time-travel   |\n| `mem_write`          | `memory:write`     | record a belief into private memory (bitemporal, revision-aware)    |\n| `mem_forget`         | `memory:write`     | retract one of your own beliefs (soft, bitemporal)                  |\n\nSee **[What counts as knowledge](docs/knowledge-unit.md)** for the Knowledge Unit\ncontract (what may become stored knowledge), **[Evals \u0026 limits](docs/evals.md)**\nfor what we measure and **what we don't claim**, **[docs/knobs.md](docs/knobs.md)**\nfor the optional answer-quality knobs (Tier-B faithfulness, contested-sources,\nanswer policy, source trust), and the **[security model](docs/security-model.md)**\n(fail-closed auth, tenant RLS, lethal-trifecta analysis, supply chain).\n\nThere is **no frontend** — the only consumers are agents over MCP. The tool logic is\nframework-agnostic in `packages/shared/src/lib/knowledge/mcp-tools.ts`; the host is a\n~60-line Web-standard `fetch` handler served by Node or Bun.\n\n## 🚀 Quickstart\n\n### Run it — no clone (~1 min)\n\nNeeds Docker (Compose v2.23+) and an OpenAI-compatible key. One command pulls the\npublished images, generates secrets, brings up Postgres + server + worker, and\nprints a ready-to-paste MCP config — **no repo clone, no token minting**:\n\n```bash\nOPENAI_API_KEY=sk-... sh -c \"$(curl -fsSL https://raw.githubusercontent.com/Moai-Team-LLC/AgenticMind/main/quickstart.sh)\"\n```\n\nThe MCP endpoint comes up at `http://localhost:3000/mcp`, authenticated with a\nsingle static bearer (`MCP_API_KEY`, auto-generated). Point Claude Code / Cursor at\nit with the `Authorization: Bearer \u003cMCP_API_KEY\u003e` header.\n\n**Embeddings run locally by default** — a zero-key, offline, multilingual model\n(bge-m3) downloads on first use, so retrieval needs no cloud key. Only the\n*synthesis* step needs a chat model: `OPENAI_API_KEY` for OpenAI (the default), or\npoint `CHAT_BASE_URL` at any OpenAI-compatible endpoint — a local Ollama or vLLM.\n\nPrefer to read before you run? Same thing, explicit (just the `deploy/` drop-in, no full clone):\n\n```bash\nmkdir agenticmind \u0026\u0026 cd agenticmind\ncurl -fsSL https://raw.githubusercontent.com/Moai-Team-LLC/AgenticMind/main/deploy/docker-compose.yml -o docker-compose.yml\ncurl -fsSL https://raw.githubusercontent.com/Moai-Team-LLC/AgenticMind/main/deploy/.env.example       -o .env.example\ncurl -fsSL https://raw.githubusercontent.com/Moai-Team-LLC/AgenticMind/main/deploy/gen-secrets.sh     -o gen-secrets.sh \u0026\u0026 chmod +x gen-secrets.sh\n./gen-secrets.sh                   # writes DB password + MCP_API_KEY into .env\n# set OPENAI_API_KEY in .env, then:\ndocker compose up -d\n```\n\n### From source (development \u0026 contributing)\n\nRequires Docker and **Node ≥22.18** (or **Bun ≥1.3**) — the server and worker run on plain Node or Bun.\n\n```bash\ngit clone https://github.com/Moai-Team-LLC/AgenticMind.git\ncd AgenticMind\ncp .env.example .env.local         # set AUTH_SECRET (+ a chat key OR local Ollama)\n./setup.sh                         # picks npm or bun, starts Postgres, runs migrations\nnpm run dev                        # headless MCP server on :3000  (or: bun run dev)\n```\n\nVerify the build with `npm run check` (typecheck + tests) — `bun run check` works too.\n\nIn a from-source dev setup the `/mcp` route is fail-closed and accepts a bearer\n`typ=\"mcp\"` HS256 JWT (rather than the static deploy key). The headless server\nships no admin UI — mint one with the issuance script (it reads `DATABASE_URL` +\n`AUTH_SECRET` from your `.env.local`):\n\n```bash\nnpm run issue-token -- --label \"claude-code\" --ttl-days 365   # or: bun run issue-token --label …\n# prints the bearer on the last line — capture it, it is not stored in plaintext\n```\n\nThen point an MCP client at `http://localhost:3000/mcp` with that token as the\n`Authorization: Bearer …` header. (Lint additionally requires Node ≥22.18 — see `.nvmrc`.)\n\n\u003e **Note.** The local Docker Postgres has no TLS, so `.env.example` ships\n\u003e `DATABASE_SSL=false` and `DATABASE_URL` on host port `5435`. For managed Postgres\n\u003e (Supabase, RDS, …) that requires SSL, set `DATABASE_SSL=true`.\n\n## 🧱 Layout\n\n```text\npackages/shared/src/lib/knowledge/        ← the tiered engine (the product)\npackages/shared/src/lib/ai/               ← chat + embeddings (provider-agnostic; local embeddings by default)\npackages/shared/src/database/             ← Drizzle schema + queries (Postgres + pgvector)\napps/server/src/{index,mcp}.ts            ← headless MCP host, Node or Bun (agent surface)\napps/worker/src/jobs/knowledge-feedback/  ← Postgres-scheduled compounding sweep\n```\n\n**Architecture notes.** Agent-first and **Postgres-only**: the graph lives behind a\n`GraphStore` interface (recursive-CTE traversal on Postgres, no extra service),\ncompounding is driven by programmatic signals, MCP tokens are scoped least-privilege, the\nagent principal is slim, and the host is a headless Node/Bun HTTP server. Retrieval is **multilingual by\ndefault** — local `bge-m3` embeddings cover many languages with zero keys; full-text search\nuses the language-agnostic `simple` config (configurable per deployment).\n\n## 🌐 Ecosystem\n\nAgenticMind is the flagship **reference implementation** of\n**[the Agentic Product Standard](https://github.com/Moai-Team-LLC/agentic-product-standard)** —\nthe open standard (plus Claude Code skills) for building production-grade agentic products.\n\n|     | Repo                                                                                    | Use it when                                                                                         |\n| --- | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |\n| 📐  | **[agentic-product-standard](https://github.com/Moai-Team-LLC/agentic-product-standard)** | You're **designing or building** an agent / agentic product — the standard + skills tell you _how_. |\n| 🧠  | **AgenticMind** (this repo)                                                             | You need a **knowledge \u0026 memory layer** for your agent — a working implementation you can run.      |\n\nSee the standard's [AgenticMind case study](https://github.com/Moai-Team-LLC/agentic-product-standard/blob/main/examples/agenticmind-case-study.md) for a layer-by-layer map of how this repo implements the canon.\n\n## 🤝 Contributing \u0026 license\n\nContributions welcome — see [`CONTRIBUTING.md`](CONTRIBUTING.md). Licensed under [Apache-2.0](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoai-team-llc%2Fagenticmind","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmoai-team-llc%2Fagenticmind","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoai-team-llc%2Fagenticmind/lists"}