# Kortexio Memory **Category:** 🧠 Knowledge & Memory **Repository:** https://github.com/Kortexio/ContextMemory **Views:** 0 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/kortexio-memory ## Description Hosted ambient memory for AI agents. Retrieve context and save notes via MCP tools with OAuth. ## Claude Desktop Quick Installation Heuristic fallback β€” verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low): ```json "mcpServers": { "kortexio-memory": { "command": "npx", "args": ["-y","kortexio-memory"] } } ``` ## Documentation & README

Kortexio ContextMemory β€” Memory you can open as a wiki

Get Cloud key Β· Self-host Β· Docs Β· Demo

License: AGPL-3.0 .NET 9 Docker GHCR Docker CI Tests GitHub commit activity

Your agent forgets. Fix that with memory you can open like a wiki.

One OpenAI-compatible /v1 URL: wiki memory, agentic tool loop, skills/guardrails, MCP, sandbox, and HITL β€” self-hosted or Cloud. Not a vector black box. Not classic RAG inject.

--- ## What is ContextMemory? [ContextMemory](https://github.com/Kortexio/ContextMemory) is the open-source **agentic memory gateway** behind [Kortexio](https://kortexio.io). Your app (or Cursor/Claude) keeps talking to a normal chat API. The gateway: 1. Authenticates the tenant and attaches **session wiki + history** 2. Runs an **agentic tool loop** when tools are enabled (wiki search, sandbox, MCP, …) 3. Applies **skills, guardrails, validators**, and optional **HITL** before destructive actions 4. Returns a standard OpenAI-shaped `chat.completions` response (streaming supported) ``` Your client (OpenAI SDK / Cursor MCP / curl) β”‚ β–Ό POST /v1/chat/completions β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ ContextMemory (.NET 9) β”‚ β”‚ Auth Β· session wiki Β· Global Wiki tool β”‚ β”‚ Agentic loop Β· skills Β· guardrails Β· HITL β”‚ β”‚ LLM backend (per app, OpenAI-compatible) β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β–Ό β–Ό sandbox-runtime mcp-runtime / MCP servers (shell/python/node) (HTTP + stdio, OAuth) or Azure ACA sessions ``` **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. How we compare (Mem0 / Zep / Letta / **why we are not RAG**): [`docs/compare.md`](https://github.com/Kortexio/ContextMemory/blob/HEAD/docs/compare.md). --- ## What it gives developers | You need… | ContextMemory provides… | |---|---| | Memory that survives turns without rewriting your client | Session markdown wiki + history inject; send only the new message | | Memory you can open, edit, audit | Files on disk / Postgres β€” not opaque embeddings | | Shared company/docs knowledge in chat | **Global Wiki** digests + on-demand `wiki_search` / `wiki_grep` (**not** classic RAG / embeddings) | | Point-in-time facts | Temporal revisions (`asOf` / supersede) on Global Wiki | | Tools without a second orchestrator | Same `/v1`: sandbox + MCP integrations + wiki tools | | Safer agents | Skills & guardrail packs, validators, confirmation keywords, HITL `[CONFIRM:id]` | | Cursor / Claude permanent memory fast | MCP wedge: `memory_save` / `memory_search` / `memory_get` (+ `wiki_search`, `session_recall`) | | Any LLM per tenant | Ollama, vLLM, LM Studio, OpenAI, Azure-compatible `/v1`, custom | | Operate without writing a test client | **Admin** + **Playground** (timeline, todos, artifacts, HITL) | | Full control on your infra | Docker/Compose self-host (API + Admin + mcp-runtime + sandbox) | | Zero ops | [Kortexio Cloud](https://kortexio.io) (`cmk_live_…`) | --- ## Capabilities (full surface) ### Memory - **Session wiki** β€” markdown pages, index, execution log; compaction; update every N turns; optional dedicated maintainer model; **rolling summary** in the system prompt - **History** β€” last N messages (per-app budget); mid-turn **compaction** archives long transcripts as artifacts when over `MaxContextTokens` - **Persona & rules** β€” `basePersona`, `businessRules`, `formatRules`, `wikiSchema` per app - **Global Wiki** β€” app-scoped docs; ingest/batch APIs; digests; FTS; tools `wiki_search` / `wiki_grep`; revisions / audit / `asOf` - **No vector RAG** β€” discovery is digests + lexical/FTS + tools (Cursor-style), not embeddings - **Web search** (optional) β€” enrich turns; can persist into wiki ### Agentic harness (server-side) When agentic tools are enabled, the gateway runs a tool loop: - **Iterations / timeout** β€” max steps, loop timeout, partial answer on timeout; mid-turn compaction phase - **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`) - **Lazy tool schemas** β€” MCP and built-ins listed with short/open schemas; `tool_describe` for full args - **Artifacts** β€” long outputs (and all sandbox runs) stored per session; loop keeps a short preview + `artifactId` - **Subagents** β€” `delegate_task` (depth 1, isolated child session) - **MCP tools** β€” per-app catalog (`server__tool`), allow/deny, max tools per turn, OAuth/credentials - **Validation modes** β€” `deterministic` Β· `hybrid` Β· `llm-judge` - **Hooks** β€” PreToolUse / PostToolUse guardrail kinds - **HITL** β€” pause before destructive tools; `[CONFIRM:id]` / cancel; checkpoint in session log - **Progress** β€” `context_memory.agentic` phases (incl. Compacting / Subagent*) + `context_memory.discovery` counters - **Prompt profiles** β€” `auto` / `ollama` / `openai` / `claude` / `qwen` / `composer` - **Network egress policy** β€” restricted/allowed + host allowlists ### Skills & guardrails - **Platform catalog** β€” shared skills/guardrails (Admin β†’ Skills); import `.skill.json` / `.guardrail.json` - **Activation** β€” `skill` | `always_on` | `requestable` (rules loaded via `rule_search` / `rule_read`) - **Per-app policies** β€” additive inventory on top of platform defaults - Seeded examples include anti-hallucination, tool-calling discipline, wiki-first-for-docs, privacy/secrets, transparent failures, and more - Guardrail kinds include URL fetch, sandbox claims, tool-failure disclosure, blocked patterns, pre/post tool-use hooks ### MCP (two directions) | Direction | Role | |---|---| | **Outbound wedge** | Cursor/Claude β†’ ContextMemory (`mcp-server/`) for memory tools | | **Inbound catalog** | ContextMemory agent β†’ your MCP servers (HTTP/stdio via `mcp-runtime`, OAuth, catalog rebuild) | ### Admin console Blazor Admin (`:5200`, Master Key auth) β€” operators configure tenants without touching JSON by hand: | Area | What you configure / do | |---|---| | Dashboard | Apps, requests, wiki/web-search stats | | New app / credentials | Register tenant, mint/rotate `cm_live_…` | | **Playground** | Chat Lab: agentic timeline (Compacting/Subagent), Todos, Artifacts, wiki refs, HITL | | LLM | Backend, model, endpoint, API key, history, streaming, think | | Memory & wiki | Session budgets, compaction, maintainer model, Global Wiki on/off + char budget | | Web search | Provider, mode, persist-to-wiki | | Rate limits | RPM/TPM (+ agentic weight) | | Persona & rules | Persona, business/format rules, wiki schema | | Agentic | Full gateway knobs: tools, MCP, sandbox, validators, HITL, egress | | Skills & policies | Platform + per-app skills/guardrails | | Settings | API base URL, Master Key, health |

ContextMemory Admin dashboard

LLM backend picker   Agentic gateway config

Admin Playground   Skills and guardrails

Guide: [`docs/admin-ui.md`](https://github.com/Kortexio/ContextMemory/blob/HEAD/docs/admin-ui.md) Β· HITL: [`docs/hitl.md`](https://github.com/Kortexio/ContextMemory/blob/HEAD/docs/hitl.md) ### Self-host stack Docker Compose brings up a full local platform: | Service | Role | |---|---| | **API** (`:5100`) | Gateway `/v1`, admin APIs, metrics | | **Admin** (`:5200`) | Operator UI | | **mcp-runtime** | Stdio/HTTP MCP sidecar | | **sandbox-runtime** | Isolated shell/python/node execution | Persistence: **File** (single-node) or **Postgres** (HA + FTS). Images: `ghcr.io/kortexio/contextmemory` Β· `ghcr.io/kortexio/contextmemory-admin`. ### Observability Prometheus `/metrics` Β· OpenTelemetry (Aspire) Β· per-app telemetry in Admin. --- ## Quickstart (5 minutes) ### 1. Start the gateway Default demo points at Ollama on the host. Swap the backend anytime in **Admin β†’ Config β†’ LLM** or `PATCH /admin/apps/{id}/config`. ```bash docker run --rm -p 5100:8080 \ -v contextmemory-data:/app/data \ -e ContextMemory__MasterKey=cm_master_dev_key_change_me \ -e ContextMemory__Apps__demo-dev__ApiKey=cm_live_dev_key_change_me \ -e ContextMemory__Apps__demo-dev__LlmModel=qwen3.5:9b \ -e ContextMemory__OllamaEndpoint=http://host.docker.internal:11434 \ --add-host=host.docker.internal:host-gateway \ ghcr.io/kortexio/contextmemory:latest ``` Full stack (API + Admin + MCP + sandbox): see [`docs/self-host.md`](https://github.com/Kortexio/ContextMemory/blob/HEAD/docs/self-host.md) / `docker-compose.yml`. Admin UI: typically `http://localhost:5200`. No Docker? Use **[Kortexio Cloud](https://kortexio.io)** (`cmk_live_…`) and set `CONTEXTMEMORY_BASE_URL` to the cloud API. ### 2. Wire MCP into Cursor ```bash git clone https://github.com/Kortexio/ContextMemory.git cd ContextMemory/mcp-server && npm install && node print-mcp-config.mjs ``` Paste into **Cursor β†’ Settings β†’ MCP** (or `~/.cursor/mcp.json`). Same snippet works for Claude Desktop. Details: [`mcp-server/README.md`](https://github.com/Kortexio/ContextMemory/blob/HEAD/mcp-server/README.md). ### 3. Aha (memory wedge) | Chat | You say | Agent should | |---|---|---| | **A** | `Remember: staging DB is postgres-staging-01` | `memory_save` | | **B** (new) | `What is our staging DB?` | `memory_search` + answer | CLI: `./scripts/aha-demo.sh` or `.\scripts\aha-demo.ps1` Β· storyboard: [`docs/aha-demo.html`](https://github.com/Kortexio/ContextMemory/blob/HEAD/docs/aha-demo.html) ### Cloud vs self-host | | **[Kortexio Cloud](https://kortexio.io)** | **Self-host (this repo)** | |---|---|---| | Best for | Zero ops | Full control (API + Admin + MCP + sandbox) | | Key | `cmk_live_…` (no `X-App-Id`) | `cm_live_…` + `X-App-Id` | | Chat body | Identical OpenAI `/v1` | Identical OpenAI `/v1` | Guides: [Cloud](https://github.com/Kortexio/ContextMemory/blob/HEAD/docs/cloud.md) Β· [Self-host](https://github.com/Kortexio/ContextMemory/blob/HEAD/docs/self-host.md) ### Chat drop-in ```bash curl -X POST http://localhost:5100/v1/chat/completions \ -H "Content-Type: application/json" \ -H "X-App-Id: demo-dev" -H "X-User-Id: user-42" -H "X-Session-Id: sess-abc" \ -H "Authorization: Bearer cm_live_dev_key_change_me" \ -d '{"model":"qwen3.5:9b","messages":[{"role":"user","content":"Hello"}]}' ``` Thin header helpers (**not** full SDKs): [`@kortexio/contextmemory`](https://www.npmjs.com/package/@kortexio/contextmemory) Β· [`kortexio-contextmemory`](https://pypi.org/project/kortexio-contextmemory/) --- ## Documentation & support | Doc | Topic | |---|---| | [docs/compare.md](https://github.com/Kortexio/ContextMemory/blob/HEAD/docs/compare.md) | Why it exists Β· vs Mem0 / Zep / Letta Β· **why we are not RAG** | | [docs/architecture-and-features.md](https://github.com/Kortexio/ContextMemory/blob/HEAD/docs/architecture-and-features.md) | Wiki, temporal facts, agentic, skills | | [docs/admin-ui.md](https://github.com/Kortexio/ContextMemory/blob/HEAD/docs/admin-ui.md) | Admin UI map | | [docs/hitl.md](https://github.com/Kortexio/ContextMemory/blob/HEAD/docs/hitl.md) | Human-in-the-loop | | [docs/api.md](https://github.com/Kortexio/ContextMemory/blob/HEAD/docs/api.md) | HTTP API | | [docs/cloud.md](https://github.com/Kortexio/ContextMemory/blob/HEAD/docs/cloud.md) Β· [docs/self-host.md](https://github.com/Kortexio/ContextMemory/blob/HEAD/docs/self-host.md) | Cloud Β· Docker / Compose | | [docs/ops.md](https://github.com/Kortexio/ContextMemory/blob/HEAD/docs/ops.md) | Ops & troubleshooting | | [docs/README.md](https://github.com/Kortexio/ContextMemory/blob/HEAD/docs/README.md) | Full docs index | Website: [kortexio.io](https://kortexio.io) Β· Email: [hello@kortexio.io](mailto:hello@kortexio.io) --- ## License **AGPL-3.0** for this open-source core. Commercial / hosted offerings: [kortexio.io](https://kortexio.io). See [docs/license-and-support.md](https://github.com/Kortexio/ContextMemory/blob/HEAD/docs/license-and-support.md).