Kioko

Pluggable, self-managing long-term memory for AI agents, for any framework, any language and any MCP host.

Documentation: https://aion7891.github.io/kioko-docs/ · Install: pip install kioko

The name comes from kioku (記憶), Japanese for "memory": 記 (ki) "to record" and 憶 (oku) "to remember".

Kioko remembers what users tell your agents and hands the right memories back before every reply. That covers who users are, what they prefer, what they are working towards, what they decided, which procedures work and what happened. It manages that memory by itself.

• Fifteen kinds of memory. Profile, factual, semantic, episodic, working, conversational, goal, procedural, skill, strategy, decision, graph, KV-cache, parametric, and hybrid recall over all of them. Every kind works on every store and every surface.
• A memory graph that connects them. Every new memory is linked to the memories it relates to, with a type and the evidence: a decision serves a goal, a lesson refines a procedure, a fix resolves an incident. Recall follows the links and tells the agent how things connect. The algorithm is documented in full in graph memory.
• An intelligence that manages them. It routes each turn into the right kind with the right operation: progress on a goal, a decision that replaces an earlier one, a value that changed, "forget that", a ticket number for this session. It plans which kinds a question needs, and summarises, reflects, pins hot memories and tidies up in the background. It runs offline with rules and algorithms, or with any LLM, where the algorithms gate, validate and fall back.
• Efficient by design.
  • One model call per turn at most, and none for small talk.
  • Intent-based retrieval within a token budget: about 20% fewer tokens in the measured example.
  • Rolling session summaries.
  • A stable, cacheable prompt prefix that carries the memories needed most.
• Pluggable everywhere.
  • Stores: in-process, SQLite, Postgres + pgvector, Qdrant, or your own.
  • Embedders, extractors, rankers, processors, summarizers, framework adapters, and each part of the intelligence.
  • Plug in by class, by name, or with a pip-installable entry point.
• Three ways in, one behaviour.
  • attach() for any Python agent: Agno, LangChain, LangGraph, CrewAI, OpenAI Agents SDK, AutoGen, smolagents, plain functions.
  • A REST API with OpenAPI for any language or low-code tool.
  • An MCP server for GitHub Copilot, Claude, Cursor and Copilot Studio.
• No dependencies. The core, SQLite, the offline embedder, the intelligence, the REST/MCP server and the web console use only the Python 3.14 standard library.
• You can see and steer what it does. Every write, recall and decision is an event. The web console shows them live and lets you manage every user, session and memory. Webhooks push them elsewhere.

 any Python agent ──► attach() / with_memory / MemoryMiddleware ─┐
 any language     ──► REST  /v1   (OpenAPI)                      ├──► MemoryLayer ── 15 kinds of memory
 any MCP host     ──► MCP   /mcp  or stdio                       │      │  intelligence: route · plan · maintain
 other processes  ──► RemoteMemory / connect("http://...")       ┘      └─► store: SQLite · pgvector · Qdrant · yours
                                                                             events ──► console · webhooks

Five lines

import kioko

memory = kioko.intelligent("sqlite:///plant-memory.db")      # offline; kioko.intelligent(..., llm=ask) for a model

memory.record_turn("Hi, I'm Asha, a controls engineer at the Pune plant. I prefer short answers.",
                   "Nice to meet you, Asha!", user_id="asha", session_id="mon-shift")
memory.record_turn("My goal is to get line 3 OEE above 85% by December 31.",
                   "Noted - let's track it.", user_id="asha", session_id="mon-shift")
memory.record_turn("To reset the safety relay, switch off the main breaker, then press reset for 5 seconds, "
                   "then switch the breaker back on.", "Thanks, saved.", user_id="asha", session_id="mon-shift")

print(memory.recall("The safety relay tripped again - what do I do?", user_id="asha", session_id="tue-shift"))

<memory>
Long-term memory about the user. Use it to personalise your answer. ...

Instructions from the user:
- User prefers short answers.

About the user:
- User is a controls engineer.
- User works at the Pune plant.
- User's name is Asha.

The user's open goals:
- Get line 3 OEE above 85% by December 31 (medium, 0%, due 2026-12-31)

Procedures that may apply:
- reset the safety relay: 1) Switch off the main breaker; 2) Press reset for 5 seconds; 3) Switch the breaker back on
</memory>

Each sentence went to the kind where it belongs:

• name, role and employer became profile slots;
• the answer-style preference became a standing instruction;
• the goal became a goal with a due date;
• the how-to became a procedure.

The next day's question was recognised as a how-to. No model was called. The guide continues from here, through the agent loop, frameworks, stores, the service, MCP, the console and production.

Try it without writing code:

kioko demo                                  # scripted conversation in the terminal
kioko ui --db memory.db --intelligence      # web console at http://localhost:8765 (also serves /v1 and /mcp)

Documentation

Read	For
Guide	a new user's path: install, the agent loop, frameworks, stores, service, MCP, console, production checklist, configuration, troubleshooting
Memory types	the fifteen kinds: what each remembers, its API, how it reaches the context, where the idea comes from
Intelligence	self-management: what it decides and why, LLM mode, retrieval plans, maintenance, measured savings, research basis
Graph memory	the memory graph: the linking algorithm step by step with formulas and worked examples, spreading-activation recall, feedback and decay, cost, API
Cookbook	23 runnable recipes, every kind and feature, with their real output
Stores	SQLite, Postgres + pgvector, Qdrant, Docker compose, switching embedders, writing your own store
PolicyPal	a complete example app: a company-policy chatbot for many employees, with a memory on/off toggle, a memory inspector, an accuracy evaluation and a step-by-step tutorial
Console	opening the web UI on any memory, managing users, sessions and memories, reaching it on a server, security

Pick your way in

You have	Use	Start with
A Python agent, any framework	attach()	agent = attach(agent, kioko.intelligent("sqlite:///memory.db"))
Your own agent loop	recall() + record_turn()	guide §3
Several processes or containers that must share memory	the service + connect()	kioko serve --intelligence, then connect("http://memory:8765")
Code in another language, or a low-code tool	REST API + OpenAPI	POST /v1/recall before the LLM call, POST /v1/turns after it
An MCP host (Copilot, Claude, Cursor, Copilot Studio)	MCP server	kioko mcp (stdio) or POST /mcp (HTTP)
A production database	pgvector or Qdrant	kioko.intelligent("postgresql://...") / "qdrant://host:6333/memories"
Other systems that react to memory changes	webhooks	kioko serve --webhook https://...
Your own storage, embeddings, framework or memory policy	plug-ins	@register("store" \| "embedder" \| "adapter" \| "intelligence", ...)

Install

Requires Python 3.14 or newer. On Windows, run the commands below through the launcher: py -3.14 -m ....

pip install kioko                 # the core: no third-party dependencies
pip install "kioko[pgvector]"     # + Postgres / pgvector (psycopg)
pip install "kioko[agno]"         # + the Agno adapter
pip install .                     # or from the source folder

Name. The package is kioko on PyPI. The standard romanization kioku is taken there by an unrelated cache library, and kioku-lite, kioku-agent-kit and kioku-mcp are other agent-memory projects. kioko keeps the meaning and stays distinct.