kiro-recall

A local MCP memory server for Kiro CLI that gives your AI assistant persistent, semantic memory across sessions.

Inspired by Kiro Crew's memory architecture — reimplemented as a lightweight, self-contained system using SQLite + Ollama embeddings, with Obsidian as the human-readable sync target.

What it does

• Semantic memory — structured key-value facts (pref.editor: Neovim, project.active: MyProject)
• Episodic memory — conversation fragments that decay over time (~23 day half-life)
• Lessons — corrections and rules that override all other memory (highest priority)
• Semantic recall — vector similarity search via Qwen3-Embedding (1024-dim, runs locally)
• Obsidian sync — renders memory to markdown with [[wikilinks]] for graph navigation

Architecture

┌──────────────────────────────────────────┐
│  Kiro CLI / any MCP client               │
│  Tools: Remember, Recall, Learn, Forget  │
└──────────────┬───────────────────────────┘
               │ stdio (MCP protocol)
       ┌───────▼───────┐          ┌─────────────────┐
       │  memory.db    │  sync →  │  Obsidian Vault  │
       │  (SQLite)     │          │  (Markdown)      │
       └───────┬───────┘          └─────────────────┘
               │
       ┌───────▼───────┐
       │  Ollama       │
       │  qwen3-embed  │
       │  (localhost)   │
       └───────────────┘

Requirements

• macOS or Linux
• Python 3.10+
• Ollama (for local embeddings)
• uv (recommended) or pip

Install

git clone https://github.com/fredluckham/kiro-recall.git
cd kiro-recall
bash install.sh

The install script will:

1. Install Ollama (if not present) and start it as a service
2. Pull the qwen3-embedding:0.6b model
3. Create a Python venv and install dependencies
4. Install the MCP server config into ~/.kiro/settings/mcp.json
5. Install the steering file to ~/.kiro/steering/obsidian-memory.md
6. Optionally seed memory from an existing Obsidian vault

Manual setup

If you prefer not to use the install script:#

# 1. Install Ollama and the embedding model
brew install ollama  # or: curl -fsSL https://ollama.com/install.sh | sh
brew services start ollama
ollama pull qwen3-embedding:0.6b

# 2. Create venv and install deps
uv venv .venv
uv pip install "mcp[cli]>=1.0.0" "httpx>=0.27.0"

# 3. Copy to ~/.kiro/recall
mkdir -p ~/.kiro/recall
cp server.py db.py embed.py obsidian_sync.py ~/.kiro/recall/

# 4. Add to MCP config (see install.sh for the JSON patch)

MCP Tools

Tool	Description
Remember	Store a fact, episode, or lesson
Recall	Semantic search across all memory
Learn	Store a high-priority correction/rule
Forget	Remove a memory by key or ID
MemoryStats	Show counts, age, and decay health per memory tier
PruneMemory	Hard-delete soft-deleted and fully decayed episodic rows

Memory tiers

Tier	Priority	Decay	Use case
Lessons	Highest	None	"Always use wikilinks", "Never assume region"
Semantic	High	None (updated in place)	Structured facts about user/projects
Episodic	Medium	exp(-0.03 × days)	Conversation fragments, decisions

Key format

• pref.* — User preferences (pref.theme, pref.voice, pref.editor)
• project.* — Active projects (project.active, project.stack)
• user.* — User facts (user.role, user.company, user.tools)

Obsidian sync

Run manually or via cron:

~/.kiro/recall/.venv/bin/python ~/.kiro/recall/obsidian_sync.py

Outputs:

• Memory/Semantic.md — all facts grouped by prefix
• Memory/Lessons.md — corrections grouped by category
• Sessions/YYYY-MM-DD.md — today's episodic memories

Configuration

Set the Obsidian vault path via environment variable (prompted during install, saved to ~/.kiro/recall/.env):

export KIRO_MEMORY_VAULT="$HOME/Documents/Obsidian/My Vault"

The default is ~/Documents/Obsidian/Kiro Knowledge Base.

Enable automatic Obsidian sync after every Remember or Learn call:

export KIRO_MEMORY_AUTOSYNC=1

When disabled (default), sync runs manually or via cron. Auto-sync adds a small write overhead per call but keeps the vault always current.

The Ollama endpoint is set in embed.py:

OLLAMA_URL = "http://localhost:11434/api/embed"
MODEL = "qwen3-embedding:0.6b"

License

MIT