LucieEveille/kiwi-mem

🥝 kiwi‑mem – AI‑as‑a‑brain

What it is

• A self‑hosted gateway that sits between a chat client and large‑language‑model (LLM) APIs (OpenAI‑compatible or Anthropic native). It injects human‑like long‑term memory into every request and extracts new memories from the model’s replies.

Key ideas

• Memory heat – each stored fact has a “temperature”. It cools over time, heats up when the conversation revisits it, and cools faster if it’s rarely mentioned. Hot memories are injected fully, warm ones as summaries, cold ones are ignored.
• Dream (sleep) cycle – a nightly process that cleans up stale fragments, merges related pieces into memory scenes, and runs a small inference step to infer unstated facts. The result is stored back as high‑level memories.
• Calendar compression – chat logs are automatically rolled up into hierarchical summaries (day → week → month → quarter → year) so older periods occupy only a few tokens.
• Conflict resolution & locking – when a new fact contradicts an old one, the old entry is deprecated. Users can lock important memories so they never decay.
• Token‑saving prompt layout – static data (persona, locked memories, calendar) is placed in a cached prefix, dynamic data (search results, sleep hints) follows, cutting up to ~90 % of input‑token cost.

How it works

1. Your chat client sends a request to https://your‑domain/v1/chat/completions (the kiwi‑mem gateway).
2. The gateway looks up relevant memories using a hybrid RRF search (vector + keyword) and prepends them to the prompt according to their heat level.
3. The request is forwarded to the configured LLM provider.
4. The LLM’s reply is returned to the client and parsed for new memory fragments, which are stored with an initial heat.
5. Periodically (or on demand) the Dream job runs to consolidate and infer.

Main features

Feature	What it does
Heat‑based decay & reinforcement	Memories fade automatically; repeated mentions re‑heat them.
Dream sleep integration	Three‑stage cleaning, merging, and foresight inference.
Hierarchical calendar	Daily → weekly → monthly → quarterly → yearly summaries, injected with decreasing detail.
Conflict handling	New contradictory facts deactivate older ones; locked memories stay forever.
Tool drawer	Over 20 built‑in tools (search, reminders, web‑search, etc.) are loaded only when the system predicts they’re needed, saving tokens.
Multi‑provider support	Works with any OpenAI‑compatible endpoint and Anthropic’s native API without extra translation.
Project isolation	Global memory is shared, but each “project” can have private instructions, files and conversation history that never leak to other projects.
Web admin panel	Configure providers, view/ edit memories, run Dream, manage projects, export/import backups.
Docker‑first deployment	docker compose up -d starts the whole stack (FastAPI gateway + PostgreSQL + pgvector).

Tech stack

• Python + FastAPI – the HTTP gateway and memory logic.
• PostgreSQL with pgvector – stores memories, embeddings and heat values.
• Docker / Docker‑Compose – one‑click deployment, portable across VPS, cloud VMs or platforms like Zeabur.
• AGPL‑3.0‑or‑later – ensures any hosted modifications remain open source.

Who it’s for

• Personal AI assistants that should remember your habits, preferences, health data, etc.
• Long‑term chat companions (emotional support, role‑play, storytelling).
• Creative partners that need to retain world‑building details across many sessions.
• Study tutors that keep track of your progress and weak points.

Getting started (quick‑run)

# on a fresh server
curl -fsSL https://get.docker.com | sh
git clone https://github.com/LucieEveille/kiwi-mem.git
cd kiwi-mem
cp .env.example .env   # edit only if you want to pre‑fill API_KEY
docker compose up -d

• Verify with curl http://localhost:8080 → {"status":"running"}.
• Open https://your‑domain/admin (no password by default) to add an LLM provider, test the connection, and start chatting through any client that supports OpenAI‑style APIs.

Updating

• Run bash scripts/update.sh – it backs up the DB, pulls the latest code, rebuilds the container, and rolls back automatically if the new version fails to start.
• Optional cron install (--install‑cron) for daily auto‑updates.

Limitations

• Designed for personal memory, not for enterprise document‑search or knowledge‑graph use cases.
• The gateway itself has no authentication; you must protect the endpoint (e.g., Cloudflare Access, basic auth, IP allow‑list) if it’s exposed publicly.

License

• AGPL‑3.0‑or‑later – you may use, modify, and redistribute, but if you provide the service over a network you must make the source (including your changes) available to users.

---

kiwi‑mem aims to give you an AI that truly “remembers you”, with forgetting and consolidation that mimic human memory.