Deterministic memory for AI agents

Store facts. Not transcripts.

ai-knot is a self-hosted memory layer for agents — with no LLM on the read path or the write path. It keeps structured knowledge in SQLite, PostgreSQL, or YAML, recalls only what the next turn needs — for one agent or a whole team — and drops into your stack in one line: MCP, HTTP, or native framework adapters.

Open the repo Inspect the benchmarks Read the whitepaper
No LLM on read or write MCP + frameworks + HTTP Shared memory for teams of agents
0 LLM Calls needed on the read or write path — run it fully air-gapped
$0 Per memory op — no tokens, no API keys, milliseconds on the read path
78.0% LoCoMo QA accuracy, cat1-4, with every knob named

The wedge is reliability, not more context.

Most agents still treat memory as a growing transcript. ai-knot treats memory as a knowledge layer: extract or add facts, store them in your own backend, and recall only the few facts the next turn needs.

Regression-testable recall Bi-temporal memory Multi-agent governance
from ai_knot import KnowledgeBase kb = KnowledgeBase(agent_id="assistant") kb.add("Preferred language is Python") kb.add("API framework is FastAPI") kb.add("Primary database is PostgreSQL") print(kb.search("what stack does the user use?")) # alias: kb.recall(...) # [1] Primary database is PostgreSQL # [2] API framework is FastAPI # [3] Preferred language is Python
Terminal loop: ai-knot add / learn → ai-knot search → ai-knot list → ai-knot delete

Why developers try it

Deterministic by design

Recall is cheap, auditable, and consistent. You can write tests against it instead of treating memory as an opaque side effect.

Self-hosted with no lock-in

Keep the same API while switching between YAML, SQLite, and PostgreSQL. The store stays inspectable and under your control.

Multiple adoption surfaces

Start from the environment you already use: plain Python callables, MCP, CrewAI, LlamaIndex, LangGraph, AutoGen, OpenAI Agents SDK, PydanticAI, HTTP, TypeScript, notebook, or browser inspector.

Pick the surface that matches your stack

Python core

Start with ai-knot demo for the installed proof, then drop to KnowledgeBase.add() and search() / recall() when you want the raw API.

Quickstart
MCP clients

One-command default-config setup for Claude Desktop, Claude Code, and OpenClaw on supported platforms. Try ai-knot setup openclaw --agent-id assistant --storage sqlite --write-default-config, then ai-knot doctor --json. Use serve-mcp for remote Streamable HTTP hosts.

MCP guide
Browser inspector

Read-only memory viewer for demos, debugging, and trust-building.

Seeded demo
Notebook walkthrough

Rendered zero-network tutorial with outputs already visible on GitHub.

Open notebook
CrewAI

Use Crew(memory=...) or memory.scope(...).

CrewAI proof
Function-calling runtimes

Use create_basic_memory_functions(...) when your runtime wants plain Python callables instead of LangChain tool objects.

Callable proof
LangGraph

Use create_basic_memory_tools(...) for the explicit add/search/list/delete loop, add create_get_memory_tool(...) or include_get=True for targeted by-id inspection, or keep create_manage_memory_tool(...) plus create_search_memory_tool(...).

LangGraph proof
LlamaIndex

Use AiKnotLlamaIndexMemory through the native memory=... seam.

LlamaIndex proof
PydanticAI

Append recalled facts through runtime instructions=....

PydanticAI proof
AutoGen

Attach AiKnotAutoGenMemory to AssistantAgent.

AutoGen proof
HTTP + TypeScript

Use HttpKnowledgeBase over the HTTP sidecar when your runtime should not spawn the local MCP subprocess, and use npx ai-knot-doctor when you do want the npm bridge path. The sidecar path also keeps learn([...]) and addResolved([...]), including explicit op values for update/delete/noop memory correction.

HTTP guide HTTP proof

Fastest ways to try it

The repo already includes multiple no-surprises entry points. Use the one that matches how you evaluate developer tools.

Zero local setup

Open the repo in Codespaces, then run the install-free first commands from docs/codespaces-quickstart.md.

One-command visual proof

Run python examples/browser_inspector_demo.py and open /inspect.

Examples by surface

Open examples/README.md for the quickest zero-network or real wiring proof by stack.

CLI-first proof

Run ai-knot demo for the built-in add / search / list / get / delete proof, then switch to learn when you want LLM-based extraction.

Installed npm proof

Run npm install ai-knot then npx ai-knot-demo when you want to verify the packaged Node bridge before writing TypeScript app code.

Remote MCP proof

Run ai-knot serve-mcp assistant --port 8765 when your host supports HTTP MCP instead of stdio.

Skeptical path

Inspect docs/benchmarks.md and re-run the deterministic suite.

Docs and research

Memory commands

One cross-surface command map for add, search, list, and delete.

Open the guide
Whitepaper

Why agent memory should be treated as a knowledge layer, not a log.

Read it
Developer guide

Practical guide for adding deterministic memory to an agent in under 30 minutes.

Read it
Benchmark methodology

Named-reader QA numbers plus deterministic retrieval numbers.

Inspect the numbers
Comparison guide

When to choose ai-knot vs Mem0, Graphiti, Letta, or LangMem.

Compare trade-offs
FAQ

Short answers for evaluation questions, objections, and skeptical readers.

Open FAQ
Integrations guide

Find the right install path and surface for CrewAI, LangGraph, LlamaIndex, MCP, HTTP, and TypeScript.

Browse integrations