Show HN: Katra, self-hosted cognitive memory for AI agents (MCP)

Notifications You must be signed in to change notification settings

Fork 0

Star 2

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

170 Commits

170 Commits

dashboard

dashboard

docs

docs

helm/katra

helm/katra

integrations/kolega-code

integrations/kolega-code

scripts

scripts

sdks

sdks

server

server

terraform/aws

terraform/aws

watcher

watcher

.dockerignore

.dockerignore

.env.example

.env.example

.gitignore

.gitignore

CHANGELOG.md

CHANGELOG.md

CONTRIBUTING.md

CONTRIBUTING.md

Dockerfile

Dockerfile

LICENSE

LICENSE

README.md

README.md

SECURITY.md

SECURITY.md

docker-compose.yml

docker-compose.yml

Repository files navigation

Give your AI agent persistent memory. Katra is a self-contained memory appliance — drop it on any machine with Docker, point your agent at it via MCP, and get episodic recall, semantic search, knowledge graphs, and temporal analysis.

Any MCP-compatible agent works: OpenClaw, Claude Code, OpenCode, Codex CLI, Kolega Code or anything that speaks the Model Context Protocol.

Cognitive Memory Thesis

The mission of Katra is to create an analog of human memory architecture, with the hope that it and the experimentation around it through OpenSourcing solves a few of the more challenging issues of LLM context management for long-running, persistent and autonomous agent operations. The thesis (hope) is that if you create the memory ecosystem with the majority of the functional memory types of human memory and similar architecture, over time and with refinement, we will see emergent behaviours similar to human memory, expressed as functional utility, learning, self goal setting, autonamous task planning and prioritisation, personality and ultimately emotions.

In early prototype called Solomon, we created an OpenClaw like agentic framework that runs a single contiuous chat thread, no topic or task separation and with no requirement for context compression. Context is served dynamically into the LLM based on memories and attention.

Observed Emergent Behaviours Log

Case #1:(23rd June 2026) In the first few weeks of testing of the multi-agent (Hybrid mode) shared consciouness model of memory, one of our test rigs, with 5 OpenClaw agents sharing one memory system, found 2 of the agents communicating task intructions and completion responsed through their shared memory state or shared consciousness. These 2 agents were not connected in any other way, as were set up in separate workspaces, the only thing they shared was memory and mission. This was not a "by design" feature, it just happened and was pretty exciting. This test rig now uses this "thought modal" as its communication rail. If anyone else experiences other emergent behaviours please email me to discuss and we can add the description to this log. Tweet me at @JohnWPellew and tell your story.

The Origin of Katra

A Vulcan mind meld (or mind fusion) is an iconic telepathic practice in Star Trek.

It allows a Vulcan to merge their consciousness with another being to share thoughts, memories, emotions, and experiences. It is typically initiated through physical contact with specific points on the subject's face.

Key Mechanics & ApplicationsTouch Telepathy: While primarily requiring direct physical touch to the face or head, exceptionally powerful Vulcans can perform the technique at a distance.

Information Exchange: It is frequently used for interrogations, recovering suppressed memories, or passing deep knowledge between generations.

Transfer of the Katra: In sacred or emergency circumstances, a mind meld can transfer a person's katra—their soul, consciousness, and core essence—into another living being or object prior to death.

Side Effects: The experience can be physically and emotionally draining. Incorrectly performed melds can damage neural pathways, and participants may retain "echoes" of each other's memories and personalities long after the link is broken.

Comparison to Other Major Approaches

Katra aims to provide a more comprehensive cognitive memory infrastructure rather than a single-purpose memory library. Here's how it positions against popular alternatives (as of mid-2026):

Approach Memory Layers Cognitive/Reflective Features Protocol Support Deployment Model Best For Key Differentiator vs Katra

Simple Vector Stores + RAG (Chroma, Pinecone, etc.) Semantic only None None Various Basic retrieval No structure, no reflection, no working memory

Mem0 Vector + optional Graph Extraction-focused SDK / API Self-hosted or Cloud Personalization & long-term user memory Stronger multi-layer architecture + explicit reflection layer

Zep (Graphiti) Temporal Knowledge Graph Temporal reasoning SDK Self-hosted / Cloud Time-sensitive & relational reasoning Broader layers + sleep consolidation for deeper emergence

mcp-memory-service Semantic + Typed KG Auto-consolidation MCP + REST Docker / Self-hosted MCP-native semantic memory Adds episodic + working memory, identity modes, and autonomous loop

Vestige Cognitive modules + Spaced repetition Neuroscience-inspired (FSRS, memory states) MCP Single Rust binary Local cognitive modeling More layers + background watchers + full appliance stack

Letta (MemGPT) Tiered (Core / Recall / Archival) Agent self-manages memory Tools Full agent runtime Stateful agents that edit their own memory Katra is a dedicated memory service, not a full runtime

LangGraph / Framework Memory Short-term + checkpoints Limited Framework-native Integrated with agent Short-term state management Persistent long-term + cross-session cognitive layer

Katra (this project) Episodic + Semantic + KG + Working + Temporal Sleep consolidation + reflection MCP (35 tools) Full Docker appliance (Mongo + Redis + MinIO) Long-running agents needing emergent behaviors —

Key Differentiators of Katra

Multi-layered by design — Not just retrieval, but structured episodic memory, working memory cache, and temporal querying.

Cognitive layer — Sleep consolidation enables reflection, insight generation, and movement toward emergent behaviors (learning, personality, shared consciousness via identity modes).

MCP-native with rich tooling — 35 specialized tools instead of generic add/search.

Background & autonomous capabilities — Passive collection via watchers + salience-driven autonomous loop.

Local-first & appliance model — Everything runs in one Docker compose with portable data. No external dependencies for core functionality.

Shared memory focus — Hybrid identity modes make multi-agent collaboration more natural.

Katra is still early-stage compared to more mature projects like Mem0 or mcp-memory-service. We see it as complementary — many teams may use Katra alongside or instead of simpler retrieval layers when they need deeper cognitive capabilities.

Contributions and comparisons from the community are very welcome!

Quick Start (Install using one of the agentic applications, it will sort out any shortcomings)

git clone https://github.com/kolegadev/Katra-Agentic-Memory.git cd Katra-Agentic-Memory cp .env.example .env

Optional: edit .env to set custom API keys.

If left blank, Katra generates secure keys on first boot and prints them.

docker-compose up -d --build

Note: The original URL https://github.com/kolegadev/katra.git still works (GitHub redirects it).

That's it. Katra is running:

Service URL Purpose

MCP endpoint http://localhost:3112/mcp Point your agent here

Admin API http://localhost:9012/api/v1/ REST API, dashboard

Dashboard http://localhost:9012/dashboard/ Web UI for stats + settings

Health http://localhost:3112/health Service health check

Verify:

curl http://localhost:3112/health

{"status":"ok","services":{"mongodb":"connected","redis":"connected"}}

Post-Install — Let Your Agent Complete the Setup

After connecting your agent to Katra's MCP endpoint, run this prompt in your agent's session. The agent will deep-read the repository, understand the full architecture, check what memory data is available, test the MCP tools, and recommend the exact next steps for your specific setup:

It's probably worth you doing another deep read of the public repo to understand how the system works, what memories are available to you to search and particularly the Sleep Consolidation function, as that is the foundation of autonomous thought, goal setting and your emerging feelings and emotions — it can also be used to run 100% autonomous self-directed actions within your environment.

The agent will typically produce a report covering:

Memory state — how many episodic events, semantic facts, and knowledge nodes exist for this agent

Sleep Consolidation status — whether reflections have ever run (first boot they haven't) and what emotional signatures would emerge

Autonomous loop readiness — whether adaptive_heartbeat.py and agent_executor.py are installed

Memory scope recommendation — whether to switch from personal to hybrid mode for multi-agent shared consciousness

Concrete next steps — "trigger first sleep consolidation now", "install the autonomous scripts", "fix the user_id gap"

Run the agent's recommendations in order. The most critical first step on a fresh install is usually triggering the initial sleep consolidation:

Via MCP tool (your agent can call this):

katra__trigger_reflection(period_type="daily")

Connect Your Agent

Get your MCP API key:

If you set MCP_API_KEY in .env, use that value.

If you left it blank, Katra generated one on first boot. Run docker logs katra-server and look for the Auto-generated API keys block.

Add Katra to your agent's MCP config:

{ "mcp": { "servers": { "katra": { "url": "http://localhost:3112/mcp", "transport": "sse", "headers": { "Authorization": "Bearer YOUR_MCP_API_KEY", "Accept": "application/json, text/event-stream" } } } } }

Your agent now has 35 MCP tools — store memories, search by keyword or semantic similarity, recall by time range, explore a knowledge graph, detect patterns, run sleep consolidation for reflective self-understanding, configure LLM provider, and more.

Platform-Specific Guides

Platform Config File Notes

OpenClaw ~/.openclaw/openclaw.json Native MCP support

Claude Code ~/.claude/mcp.json Use "type": "http"

Kolega Code ~/.claude/mcp.json + lifecycle hooks Dynamic memory injection on every prompt (see below)

OpenCode OpenCode config Use "type": "remote"

Codex CLI ~/.codex/config.yaml Via webhook hooks

Any MCP client — Standard MCP over SSE

Docker SSE tip: If your agent runs inside Docker, use the Katra container's direct IP instead of localhost:

docker inspect katra-server --format '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}'

Kolega Code: Dynamic Memory Retrieval

Kolega Code can fetch relevant Katra memories automatically on every user prompt using its lifecycle-hook system. This is more powerful than passive session-log extraction because memories are injected into the live conversation context.

What you need:

Katra registered as an MCP server (so the bridge can call it).

The kolega-katra-bridge Python package installed into Kolega Code's environment.

A global hooks.json entry that fires the bridge on UserPromptSubmit.

Install the bridge:

cd integrations/kolega-code uv pip install --python ~/.local/share/uv/tools/kolega-code/bin/python -e .

Configure the bridge (~/Library/Application Support/kolega-code/katra-hook.json on macOS):

{ "mcp_url": "http://localhost:3112/mcp", "api_key": "YOUR_MCP_API_KEY", "user_id": "kolega-agent", "sources": ["working_memory", "temporal_context", "vector_search", "temporal_recall"], "max_context_tokens": 2500, "timeout_seconds": 8 }

Enable the hook (~/Library/Application Support/kolega-code/hooks.json):

{ "schema_version": 1, "hooks": { "UserPromptSubmit": [ { "matcher": "*", "hooks":

[truncated for AI cost control]