Kortexio Memory README

Get Cloud key · Self-host · Docs · Demo

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 is the open-source agentic memory gateway behind Kortexio.

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.

What it gives developers

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)

Admin console

Blazor Admin (:5200, Master Key auth) — operators configure tenants without touching JSON by hand:

Guide: docs/admin-ui.md · HITL: docs/hitl.md

Self-host stack

Docker Compose brings up a full local platform:

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.

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 / docker-compose.yml.

Admin UI: typically http://localhost:5200.

No Docker? Use Kortexio Cloud (cmk_live_…) and set CONTEXTMEMORY_BASE_URL to the cloud API.

2. Wire MCP into Cursor

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.

3. Aha (memory wedge)

CLI: ./scripts/aha-demo.sh or .\scripts\aha-demo.ps1 · storyboard: docs/aha-demo.html

Cloud vs self-host

Guides: Cloud · Self-host

Chat drop-in

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 · kortexio-contextmemory

Documentation & support

Website: kortexio.io · Email: hello@kortexio.io

License

AGPL-3.0 for this open-source core. Commercial / hosted offerings: kortexio.io. See docs/license-and-support.md.