{
  "markdown": "<p align=\"center\">\n  <a href=\"https://github.com/Kortexio/ContextMemory\">\n    <img src=\"docs/images/banner-sm.svg\" width=\"800\" alt=\"Kortexio ContextMemory — Memory you can open as a wiki\">\n  </a>\n</p>\n\n<p align=\"center\">\n  <a href=\"https://kortexio.io\"><strong>Get Cloud key</strong></a>\n  ·\n  <a href=\"#quickstart-5-minutes\">Self-host</a>\n  ·\n  <a href=\"docs/README.md\">Docs</a>\n  ·\n  <a href=\"docs/aha-demo.html\">Demo</a>\n</p>\n\n<p align=\"center\">\n  <a href=\"LICENSE\"><img src=\"https://img.shields.io/badge/License-AGPL%203.0-blue.svg\" alt=\"License: AGPL-3.0\"></a>\n  <a href=\"https://dotnet.microsoft.com/\"><img src=\"https://img.shields.io/badge/.NET-9.0-512BD4\" alt=\".NET 9\"></a>\n  <a href=\"https://github.com/users/Kortexio/packages/container/package/contextmemory\"><img src=\"https://img.shields.io/badge/ghcr.io-contextmemory-blue?logo=docker\" alt=\"Docker GHCR\"></a>\n  <a href=\"https://github.com/Kortexio/ContextMemory/actions/workflows/docker-publish.yml\"><img src=\"https://github.com/Kortexio/ContextMemory/actions/workflows/docker-publish.yml/badge.svg\" alt=\"Docker CI\"></a>\n  <a href=\"https://github.com/Kortexio/ContextMemory/actions/workflows/dotnet-tests.yml\"><img src=\"https://img.shields.io/github/actions/workflow/status/Kortexio/ContextMemory/dotnet-tests.yml?branch=main&label=tests\" alt=\"Tests\"></a>\n  <a href=\"https://github.com/Kortexio/ContextMemory/commits/main\"><img src=\"https://img.shields.io/github/commit-activity/m/Kortexio/ContextMemory?style=flat-square\" alt=\"GitHub commit activity\"></a>\n</p>\n\n<p align=\"center\">\n  <strong>Your agent forgets. Fix that with memory you can open like a wiki.</strong>\n</p>\n\n<p align=\"center\">\n  One OpenAI-compatible <code>/v1</code> URL: wiki memory, agentic tool loop, skills/guardrails, MCP, sandbox, and HITL —\n  self-hosted or <a href=\"https://kortexio.io\">Cloud</a>. Not a vector black box. Not classic RAG inject.\n</p>\n\n---\n\n## What is ContextMemory?\n\n[ContextMemory](https://github.com/Kortexio/ContextMemory) is the open-source **agentic memory gateway** behind [Kortexio](https://kortexio.io).\n\nYour app (or Cursor/Claude) keeps talking to a normal chat API. The gateway:\n\n1. Authenticates the tenant and attaches **session wiki + history**\n2. Runs an **agentic tool loop** when tools are enabled (wiki search, sandbox, MCP, …)\n3. Applies **skills, guardrails, validators**, and optional **HITL** before destructive actions\n4. Returns a standard OpenAI-shaped `chat.completions` response (streaming supported)\n\n```\nYour client (OpenAI SDK / Cursor MCP / curl)\n        │\n        ▼  POST /v1/chat/completions\n┌────────────────────────────────────────────┐\n│  ContextMemory (.NET 9)                    │\n│  Auth · session wiki · Global Wiki tool    │\n│  Agentic loop · skills · guardrails · HITL │\n│  LLM backend (per app, OpenAI-compatible)  │\n└───────┬──────────────────┬─────────────────┘\n        ▼                  ▼\n sandbox-runtime      mcp-runtime / MCP servers\n (shell/python/node)  (HTTP + stdio, OAuth)\n or Azure ACA sessions\n```\n\n**Honest boundaries:** this is a **gateway + server-side harness**, not a client agent framework (LangGraph/CrewAI) and not an agent OS (Letta). You keep your OpenAI client; the loop runs on the server.\n\nHow we compare (Mem0 / Zep / Letta / **why we are not RAG**): [`docs/compare.md`](docs/compare.md).\n\n---\n\n## What it gives developers\n\n| You need… | ContextMemory provides… |\n|---|---|\n| Memory that survives turns without rewriting your client | Session markdown wiki + history inject; send only the new message |\n| Memory you can open, edit, audit | Files on disk / Postgres — not opaque embeddings |\n| Shared company/docs knowledge in chat | **Global Wiki** digests + on-demand `wiki_search` / `wiki_grep` (**not** classic RAG / embeddings) |\n| Point-in-time facts | Temporal revisions (`asOf` / supersede) on Global Wiki |\n| Tools without a second orchestrator | Same `/v1`: sandbox + MCP integrations + wiki tools |\n| Safer agents | Skills & guardrail packs, validators, confirmation keywords, HITL `[CONFIRM:id]` |\n| Cursor / Claude permanent memory fast | MCP wedge: `memory_save` / `memory_search` / `memory_get` (+ `wiki_search`, `session_recall`) |\n| Any LLM per tenant | Ollama, vLLM, LM Studio, OpenAI, Azure-compatible `/v1`, custom |\n| Operate without writing a test client | **Admin** + **Playground** (timeline, todos, artifacts, HITL) |\n| Full control on your infra | Docker/Compose self-host (API + Admin + mcp-runtime + sandbox) |\n| Zero ops | [Kortexio Cloud](https://kortexio.io) (`cmk_live_…`) |\n\n---\n\n## Capabilities (full surface)\n\n### Memory\n\n- **Session wiki** — markdown pages, index, execution log; compaction; update every N turns; optional dedicated maintainer model; **rolling summary** in the system prompt\n- **History** — last N messages (per-app budget); mid-turn **compaction** archives long transcripts as artifacts when over `MaxContextTokens`\n- **Persona & rules** — `basePersona`, `businessRules`, `formatRules`, `wikiSchema` per app\n- **Global Wiki** — app-scoped docs; ingest/batch APIs; digests; FTS; tools `wiki_search` / `wiki_grep`; revisions / audit / `asOf`\n- **No vector RAG** — discovery is digests + lexical/FTS + tools (Cursor-style), not embeddings\n- **Web search** (optional) — enrich turns; can persist into wiki\n\n### Agentic harness (server-side)\n\nWhen agentic tools are enabled, the gateway runs a tool loop:\n\n- **Iterations / timeout** — max steps, loop timeout, partial answer on timeout; mid-turn compaction phase\n- **Built-in tools** — `wiki_search`, `wiki_grep`; sandbox `shell_execute` / `python_execute` / `node_execute` / `container_execute` (self-hosted or ACA); discovery helpers (`artifact_*`, `skill_*`, `rule_*`, `tool_describe`, `session_log_search`, `delegate_task`, `todo_write`)\n- **Lazy tool schemas** — MCP and built-ins listed with short/open schemas; `tool_describe` for full args\n- **Artifacts** — long outputs (and all sandbox runs) stored per session; loop keeps a short preview + `artifactId`\n- **Subagents** — `delegate_task` (depth 1, isolated child session)\n- **MCP tools** — per-app catalog (`server__tool`), allow/deny, max tools per turn, OAuth/credentials\n- **Validation modes** — `deterministic` · `hybrid` · `llm-judge`\n- **Hooks** — PreToolUse / PostToolUse guardrail kinds\n- **HITL** — pause before destructive tools; `[CONFIRM:id]` / cancel; checkpoint in session log\n- **Progress** — `context_memory.agentic` phases (incl. Compacting / Subagent*) + `context_memory.discovery` counters\n- **Prompt profiles** — `auto` / `ollama` / `openai` / `claude` / `qwen` / `composer`\n- **Network egress policy** — restricted/allowed + host allowlists\n\n### Skills & guardrails\n\n- **Platform catalog** — shared skills/guardrails (Admin → Skills); import `.skill.json` / `.guardrail.json`\n- **Activation** — `skill` | `always_on` | `requestable` (rules loaded via `rule_search` / `rule_read`)\n- **Per-app policies** — additive inventory on top of platform defaults\n- Seeded examples include anti-hallucination, tool-calling discipline, wiki-first-for-docs, privacy/secrets, transparent failures, and more\n- Guardrail kinds include URL fetch, sandbox claims, tool-failure disclosure, blocked patterns, pre/post tool-use hooks\n\n### MCP (two directions)\n\n| Direction | Role |\n|---|---|\n| **Outbound wedge** | Cursor/Claude → ContextMemory (`mcp-server/`) for memory tools |\n| **Inbound catalog** | ContextMemory agent → your MCP servers (HTTP/stdio via `mcp-runtime`, OAuth, catalog rebuild) |\n\n### Admin console\n\nBlazor Admin (`:5200`, Master Key auth) — operators configure tenants without touching JSON by hand:\n\n| Area | What you configure / do |\n|---|---|\n| Dashboard | Apps, requests, wiki/web-search stats |\n| New app / credentials | Register tenant, mint/rotate `cm_live_…` |\n| **Playground** | Chat Lab: agentic timeline (Compacting/Subagent), Todos, Artifacts, wiki refs, HITL |\n| LLM | Backend, model, endpoint, API key, history, streaming, think |\n| Memory & wiki | Session budgets, compaction, maintainer model, Global Wiki on/off + char budget |\n| Web search | Provider, mode, persist-to-wiki |\n| Rate limits | RPM/TPM (+ agentic weight) |\n| Persona & rules | Persona, business/format rules, wiki schema |\n| Agentic | Full gateway knobs: tools, MCP, sandbox, validators, HITL, egress |\n| Skills & policies | Platform + per-app skills/guardrails |\n| Settings | API base URL, Master Key, health |\n\n<p align=\"center\">\n  <img src=\"docs/images/admin-dashboard.png\" width=\"800\" alt=\"ContextMemory Admin dashboard\">\n</p>\n\n<p align=\"center\">\n  <img src=\"docs/images/admin-llm-backend.png\" width=\"390\" alt=\"LLM backend picker\">\n  &nbsp;\n  <img src=\"docs/images/admin-agentic.png\" width=\"390\" alt=\"Agentic gateway config\">\n</p>\n\n<p align=\"center\">\n  <img src=\"docs/images/admin-playground.png\" width=\"390\" alt=\"Admin Playground\">\n  &nbsp;\n  <img src=\"docs/images/admin-skills.png\" width=\"390\" alt=\"Skills and guardrails\">\n</p>\n\nGuide: [`docs/admin-ui.md`](docs/admin-ui.md) · HITL: [`docs/hitl.md`](docs/hitl.md)\n\n### Self-host stack\n\nDocker Compose brings up a full local platform:\n\n| Service | Role |\n|---|---|\n| **API** (`:5100`) | Gateway `/v1`, admin APIs, metrics |\n| **Admin** (`:5200`) | Operator UI |\n| **mcp-runtime** | Stdio/HTTP MCP sidecar |\n| **sandbox-runtime** | Isolated shell/python/node execution |\n\nPersistence: **File** (single-node) or **Postgres** (HA + FTS). Images: `ghcr.io/kortexio/contextmemory` · `ghcr.io/kortexio/contextmemory-admin`.\n\n### Observability\n\nPrometheus `/metrics` · OpenTelemetry (Aspire) · per-app telemetry in Admin.\n\n---\n\n## Quickstart (5 minutes)\n\n### 1. Start the gateway\n\nDefault demo points at Ollama on the host. Swap the backend anytime in **Admin → Config → LLM** or `PATCH /admin/apps/{id}/config`.\n\n```bash\ndocker run --rm -p 5100:8080 \\\n  -v contextmemory-data:/app/data \\\n  -e ContextMemory__MasterKey=cm_master_dev_key_change_me \\\n  -e ContextMemory__Apps__demo-dev__ApiKey=cm_live_dev_key_change_me \\\n  -e ContextMemory__Apps__demo-dev__LlmModel=qwen3.5:9b \\\n  -e ContextMemory__OllamaEndpoint=http://host.docker.internal:11434 \\\n  --add-host=host.docker.internal:host-gateway \\\n  ghcr.io/kortexio/contextmemory:latest\n```\n\nFull stack (API + Admin + MCP + sandbox): see [`docs/self-host.md`](docs/self-host.md) / `docker-compose.yml`.\n\nAdmin UI: typically `http://localhost:5200`.\n\nNo Docker? Use **[Kortexio Cloud](https://kortexio.io)** (`cmk_live_…`) and set `CONTEXTMEMORY_BASE_URL` to the cloud API.\n\n### 2. Wire MCP into Cursor\n\n```bash\ngit clone https://github.com/Kortexio/ContextMemory.git\ncd ContextMemory/mcp-server && npm install && node print-mcp-config.mjs\n```\n\nPaste into **Cursor → Settings → MCP** (or `~/.cursor/mcp.json`). Same snippet works for Claude Desktop. Details: [`mcp-server/README.md`](mcp-server/README.md).\n\n### 3. Aha (memory wedge)\n\n| Chat | You say | Agent should |\n|---|---|---|\n| **A** | `Remember: staging DB is postgres-staging-01` | `memory_save` |\n| **B** (new) | `What is our staging DB?` | `memory_search` + answer |\n\nCLI: `./scripts/aha-demo.sh` or `.\\scripts\\aha-demo.ps1` · storyboard: [`docs/aha-demo.html`](docs/aha-demo.html)\n\n### Cloud vs self-host\n\n| | **[Kortexio Cloud](https://kortexio.io)** | **Self-host (this repo)** |\n|---|---|---|\n| Best for | Zero ops | Full control (API + Admin + MCP + sandbox) |\n| Key | `cmk_live_…` (no `X-App-Id`) | `cm_live_…` + `X-App-Id` |\n| Chat body | Identical OpenAI `/v1` | Identical OpenAI `/v1` |\n\nGuides: [Cloud](docs/cloud.md) · [Self-host](docs/self-host.md)\n\n### Chat drop-in\n\n```bash\ncurl -X POST http://localhost:5100/v1/chat/completions \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-App-Id: demo-dev\" -H \"X-User-Id: user-42\" -H \"X-Session-Id: sess-abc\" \\\n  -H \"Authorization: Bearer cm_live_dev_key_change_me\" \\\n  -d '{\"model\":\"qwen3.5:9b\",\"messages\":[{\"role\":\"user\",\"content\":\"Hello\"}]}'\n```\n\nThin header helpers (**not** full SDKs): [`@kortexio/contextmemory`](https://www.npmjs.com/package/@kortexio/contextmemory) · [`kortexio-contextmemory`](https://pypi.org/project/kortexio-contextmemory/)\n\n---\n\n## Documentation & support\n\n| Doc | Topic |\n|---|---|\n| [docs/compare.md](docs/compare.md) | Why it exists · vs Mem0 / Zep / Letta · **why we are not RAG** |\n| [docs/architecture-and-features.md](docs/architecture-and-features.md) | Wiki, temporal facts, agentic, skills |\n| [docs/admin-ui.md](docs/admin-ui.md) | Admin UI map |\n| [docs/hitl.md](docs/hitl.md) | Human-in-the-loop |\n| [docs/api.md](docs/api.md) | HTTP API |\n| [docs/cloud.md](docs/cloud.md) · [docs/self-host.md](docs/self-host.md) | Cloud · Docker / Compose |\n| [docs/ops.md](docs/ops.md) | Ops & troubleshooting |\n| [docs/README.md](docs/README.md) | Full docs index |\n\nWebsite: [kortexio.io](https://kortexio.io) · Email: [hello@kortexio.io](mailto:hello@kortexio.io)\n\n---\n\n## License\n\n**AGPL-3.0** for this open-source core. Commercial / hosted offerings: [kortexio.io](https://kortexio.io). See [docs/license-and-support.md](docs/license-and-support.md).\n",
  "bytes": 12983,
  "sha": "39c6c9727cb0c2fe0d46fe32f71bf036c686fc122c11f8d0fb2b2be71cee9ddb",
  "repo_slug": "kortexio/contextmemory",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_kortexio_memory_67028648/readme"
}