convez.ai
MCP ServerProdutividadeAvançado
DevOps-Nirvana

Kiro Ception

DevOps-Nirvana/Kiro-Ception

Memória persistente de IA que atravessa máquinas, projetos e meses de histórico

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server que fornece memória de longo prazo para o Kiro, indexando automaticamente todas as conversas CLI e IDE em um mecanismo de busca semântica. Processa histórico por data recente, coordena entre múltiplos computadores e oferece busca híbrida (semântica + palavras-chave) com resultado instantâneo.

Instalação

$npx convez-ai DevOps-Nirvana/Kiro-Ception

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
1
Acompanhando
0
Saúde
50%
Último commit
há 2 meses
Versão
1.0.9
Issues abertas
6
Contribuidores
3

Casos de uso

  • Recuperar soluções e decisões de projetos anteriores sem perder contexto
  • Buscar padrões de implementação usados em diferentes máquinas
  • Acessar discussões técnicas de meses atrás com busca semântica instantânea
  • Sincronizar conhecimento do Kiro entre laptop, desktop e servidores

Veredito

Solução técnica robusta para persistência de contexto em IA, com arquitetura bem pensada (dois processos, busca híbrida, federação P2P). Ideal para quem trabalha com Kiro em múltiplos ambientes e precisa de recall real de histórico; setup complexo requer comfort com DevOps.

README

A tradução para o português deste README ainda está na fila.

Kiro Ception

Your AI now remembers everything you've ever done with it, across every machine you own. Finally, an elephant-grade memory for your coding assistant, minus the 12,000-pound footprint.

Kiro Ception gives Kiro a long-term memory, persistent recall that spans every session, every window, CLI and IDE, and even across multiple machines. Your agent remembers what you discussed yesterday, last month, or six months ago, in any project, on any computer you work from. It automatically indexes all conversation history in the background and provides instant hybrid search (semantic + keyword) so you can find past discussions, decisions, and implementations by meaning, keywords, date, or any combination.

"We discussed this already..." "What was that approach we used last week?" "Didn't we solve this exact problem in the other project?" "How did I usually set up CI pipelines?"

  • All things you can now just ask, and actually get an answer.

How It Works

Kiro Ception is an MCP Power that runs as a background service alongside your Kiro IDE. It:

  1. Discovers all Kiro CLI and IDE session files on your machine
  2. Extracts meaningful messages (filtering out system prompts and boilerplate, condensing long code blocks into [code:lang] placeholders)
  3. Embeds each message into a vector representation using your configured model
  4. Indexes everything into an in-memory numpy matrix for instant hybrid search (semantic + FTS5 keyword)
  5. Serves search results via MCP tools that Kiro can call naturally during conversation
  6. Federates across machines, search your laptop and desktop simultaneously with encrypted peer-to-peer queries

Sessions are processed newest first, so your most recent conversations are searchable within seconds of startup, even while older history is still being indexed in the background.

Search results include surrounding context (messages before/after each match), relevance scores, workspace origin, and pagination, so Kiro gets the full picture of what was discussed.

Architecture Highlights

  • Two-process model: A thin MCP proxy (stdio) spawns a separate engine subprocess that holds the index in RAM. Code changes are detected via fingerprinting — the engine auto-restarts with fresh code when you git pull && uv sync.
  • Non-blocking: Heavy work (indexing, embedding) runs in the engine's background threads. The MCP proxy responds instantly.
  • Hybrid search: Combines semantic vector similarity (70%) with FTS5 full-text keyword search (30%). Find things by meaning and exact names.
  • Recency-aware: Recent conversations rank higher automatically. The decay curve scales with your history depth, no manual tuning.
  • Multi-window efficient: All MCP proxy instances share one engine process. A PID registry tracks connected clients — the engine auto-shuts-down when all clients die.
  • Multi-machine: Optional peer federation searches across all your computers simultaneously with AES-256-GCM encrypted transport.
  • Crash-safe: SQLite with WAL mode. Lose at most one in-flight message on Ctrl+C/crash/quit.
  • Instant cold-start: Loads from existing cache in under 1 second. No waiting for re-indexing after restarts.
  • No build step: Uses editable install (python -m kiro_ception.engine_main). Source changes are picked up immediately — no recompile needed.
  • Auto-migrating: Schema upgrades run automatically on startup, updates never require deleting your cache, future-proofing this tool.
  • Observable: Built-in status dashboard, indexing progress monitoring, hot-reloadable config, and health diagnostics, all accessible to the agent or via browser.

Installation

Prerequisites

  • Kiro - the AI-powered IDE
  • Git - for cloning/updating the power
  • Python 3.11+ (3.12, 3.13 also supported and tested officially)
  • uv - fast Python package manager

Install as a Kiro Power from Local Clone (Recommended)

Clone the repo and install as a local power. This gives you immediate updates via git pull and the full Power experience (keyword triggers, automatic activation, POWER.md guidance):

git clone https://github.com/DevOps-Nirvana/Kiro-Ception.git
cd Kiro-Ception
uv sync

Then in Kiro IDE: Powers panel → Add power from Local Path → select the Kiro-Ception folder you just cloned.

To update later:

cd Kiro-Ception
git pull
uv sync

Kiro picks up changes automatically — the MCP proxy detects source code changes via fingerprinting and restarts the engine process with the new code. No manual restart needed.

Install as a Kiro Power from GitHub (Alternative)

If you prefer not to manage a local clone:

  1. In Kiro IDE: Powers panel → Add power from GitHub
  2. Enter: https://github.com/DevOps-Nirvana/Kiro-Ception
  3. Click Install

Note: Due to current bugs in how Kiro handles MCP servers within Powers installed from GitHub, the local clone method above is more reliable. The GitHub install may have issues with server startup or reconnection and/or with updating due to a possible split-brain scenario.

Manual MCP Setup (Last Resort)

If you prefer manual configuration without the Power wrapper, add to your Kiro MCP configuration (~/.kiro/settings/mcp.json):

Warning: Installing as a Power (above) is strongly recommended. The POWER.md file contains keyword triggers and usage guidance that help Kiro automatically activate search when you reference past conversations. With MCP-only setup, you'll need to explicitly ask Kiro to search history — it won't trigger on its own from phrases like "as we discussed" or "what did we do last time".

{
  "mcpServers": {
    "kiro-ception": {
      "command": "uv",
      "args": ["tool", "run", "--from", "git+https://github.com/DevOps-Nirvana/Kiro-Ception", "kiro-ception"]
    }
  }
}

This uses uv tool run to fetch and run the package directly from GitHub, no local clone needed.

Alternatively, if you've cloned the repo locally:

{
  "mcpServers": {
    "kiro-ception": {
      "command": "/path/to/Kiro-Ception/.venv/bin/kiro-ception"
    }
  }
}

Replace /path/to/Kiro-Ception with the actual clone location. Usually just saving your mcp config will do it, but if needed, restart Kiro.

Configuration

Create ~/.config/kiro-ception/config.toml to customize behavior. If this file doesn't exist, sensible defaults are used (local CPU-based embeddings with all-MiniLM-L6-v2). Query the tool get_config for full information on your file location(s) for your config and database.

A full annotated default config is in config.default.toml; copy it as a starting point:

mkdir -p ~/.config/kiro-ception
cp config.default.toml ~/.config/kiro-ception/config.toml

Minimal Config (Zero Setup)

With no config file at all, Kiro Ception uses:

  • Backend: sentence-transformers (local, CPU-based, no API/GPU needed)
  • Model: all-MiniLM-L6-v2 (384 dimensions, ~80MB download on first run)
  • Sources: Auto-discovers Kiro CLI and IDE conversations in both old and new formats
  • Memory: Uses up to 1/3 of available RAM for the index (by default)

This is a good starting point; it runs entirely on CPU with no external dependencies.

GPU-Accelerated with Ollama (Recommended for Power Users)

If you have Ollama running with a GPU, you can use much larger, higher-quality embedding models by putting something like the following in your config file:

[embedding]
backend = "openai-compatible"
model = "qwen3-embedding:4b"
api_base = "http://localhost:11434/v1"
dimensions = 1024
batch_size = 1

Setup:

# Install Ollama (if not already): https://ollama.com
ollama pull qwen3-embedding:4b

This gives significantly better search quality than MiniLM, especially for nuanced queries. The 4b model runs comfortably on a 6GB+ GPU and indexes at ~3–5 messages/second.

OpenAI / Hosted Providers

[embedding]
backend = "openai-compatible"
model = "text-embedding-3-large"
api_base = "https://api.openai.com/v1"
api_key = "sk-..."
dimensions = 1024

LM Studio

[embedding]
backend = "openai-compatible"
model = "your-model-name"
api_base = "http://localhost:1234/v1"
dimensions = 768

MCP Tools

Kiro can call these tools naturally during conversation:

ToolPurpose
search_project_historySearch conversations scoped to the current workspace
search_global_historySearch across all workspaces (supports source filter: all/cli/ide)
get_indexing_statusCheck indexer progress, rate, errors, ETA
rescanTrigger a rescan for new sessions (full=True to re-read everything)
get_configShow effective config, paths, cache stats, instance role, etc
reload_configHot-reload config from disk without requiring restart of Kiro

Search Parameters

Both search tools accept:

ParameterDefaultDescription
query(required)Natural language search query
after—Only messages on/after this date (ISO 8601)
before—Only messages before this date (ISO 8601)
context_size3Messages before/after each match to include
threshold0.2Minimum similarity score (0–1)
max_results10Maximum results to return
offset0Skip results for pagination

Technologies & Libraries

ComponentLibraryPurpose
MCP Servermcp (FastMCP)Exposes tools to Kiro via Model Context Protocol
Embedding (local)sentence-transformersLocal CPU/GPU embeddings (default: all-MiniLM-L6-v2)
Embedding (API)requestsOpenAI-compatible HTTP API for Ollama/LM Studio/OpenAI
Vector SearchnumpyIn-memory cosine similarity via dot product
Data ModelsPydanticTyped data validation and serialization
CacheSQLite (stdlib)Persistent embedding + metadata storage (WAL mode)
Process CoordinationfilelockEngine process election via file locks
Encryptioncryptography + argon2-cffiAES-256-GCM peer encryption with Argon2id key derivation
BuildhatchlingPEP 517 build backend
Package ManageruvFast dependency resolution and venv management
Linter/FormatterruffLinting and formatting
TestspytestTest framework (300 tests)

Optional Features

Peer Federation

Search across multiple machines (e.g., your laptop + desktop). Each machine runs its own independent index. When you search, queries fan out to all peers in parallel and results are merged.

[peers]
enabled = true
nodes = ["192.168.1.50:19742", "workpc.tailscale:19742"]
secret = "my-shared-passphrase"  # Optional: encrypts all peer traffic with AES-256-GCM
timeout_seconds = 5

Peers communicate over HTTP. If secret is set, payloads are encrypted with AES-256-GCM (key derived via Argon2id from the passphrase). Both machines must use the same secret. Without a secret, traffic is plaintext; fine on VPNs or Tailscale or when local-only at your own house (up to you).

Memory Limits

Control how much RAM the index uses:

[memory]
fraction = 0.33     # Use up to 1/3 of RAM (default)
# limit_mb = 512    # Or set an explicit limit
# limit_mb = 0      # Disable limit (use all available)

Indexing Throttle

Reduce GPU/CPU load during active work:

[indexing]
throttle_ms = 5000   # Sleep 5000ms (5 seconds) between embedding batches (default: 0)
rescan_interval_minutes = 10  # Check for new sessions every 10 minutes (this is the default)

Once your initial index is built, it can be quite nice to add the throttle_ms value of 5-10 seconds (5000-10000) to ensure your computer runs quickly and your usage is not negatively affected. This is especially valuable if you are using a large local GPU-based model.

Secondarily, if you are trying to be sparing on battery life, and/or if you don't care about getting your index up to date so quickly, you can greatly increase the rescan interval to 60 minutes, OR you can disable this automated rescan/reindexing process by setting this to 0.

Performance

MetricValue
First-time indexing (MiniLM, CPU)~4 minutes (4300+ sessions)
First-time indexing (Qwen3-Embedding:4b, GPU)~35 minutes (4300+ sessions)
Subsequent startups<2 seconds
Search latency<10ms
Index refresh (backgrounded)Every 60 seconds
Periodic rescan to update indexes (backgrounded)Every 10 minutes
Embedding rate (Qwen3-Embedding:4b)~3–5 messages/second

Indexing order: Sessions are indexed newest first, so your most recent conversations become searchable within seconds of startup. Older conversations fill in progressively in the background.

Troubleshooting

"Backend not ready" or "still loading"

On first startup, the index eagerly loads from SQLite into RAM. If embeddings exist but metadata hasn't populated yet, you'll see a "still loading" message. Retry in a few seconds. Also, as your size of your embeddings increases this may make it take a little longer. I have six months of Kiro work across 4300 chat documents with an (currently) 300MB embedding db, and it takes 10-15 seconds to load the index into RAM.

Empty search results

  • Check get_indexing_status; indexing may still be in progress
  • Use rescan() to immediately pick up recent conversations
  • Verify your config with get_config
  • Check "Kiro Powers / MCP" log

Embedding errors / timeouts

  • For Ollama: ensure it's running (ollama ps) and the model is pulled
  • Very long messages (>50K chars) may timeout; they're skipped with a warning
  • Check your "Kiro Powers" outputs for logs/errors

Config changes not taking effect

  • Use reload_config tool (applies safe changes immediately)
  • Model/backend/dimensions changes require rescan(full=True)

Multiple windows

All Kiro windows share a single engine process automatically. Each MCP proxy registers its PID with the engine. If the engine dies, the next proxy request will respawn it. Use get_config to see the engine PID and port. If the engine has stale code (you updated the source), it will be killed and restarted automatically via fingerprint comparison.

Nuclear option

If the database is corrupt or everything is broken, find your file path to your database calling the get_config tool. Then, once you find it, uninstall this power (or disable the MCP) then remove your database, then reinstall this power (or re-enable MCP).

rm -rf ~/.cache/kiro-ception/

When you Restart Kiro (or re-enable MCP) it will rebuild the embeddings database from scratch.

Development

uv sync                         # Install deps
uv run pytest tests/ -q         # Run tests (300, ~30s)
uv run ruff check src/          # Lint
uv run kiro-ception             # Run MCP server locally

Data Locations

For information about where your data is being kept, call the MCP tool "get_config". On an unix-ey system, the file(s) at are...

PathContents
~/.config/kiro-ception/config.tomlUser configuration
~/.cache/kiro-ception/cache_<hash>.dbSQLite database (embeddings, metadata)
~/.cache/kiro-ception/engine.lockEngine process file lock
~/.cache/kiro-ception/engine.jsonEngine port/PID info for MCP proxies

The cache DB filename includes a hash of the backend configuration. Changing model/backend/dimensions creates a new DB file (old ones are preserved for rollback).

Privacy: All data is processed and stored locally on your machine. No telemetry, no external API calls, and no data leaves your device; unless you explicitly configure a third-party embedding provider (e.g., OpenAI). The default configuration uses fully local, offline embeddings.

Contributing

Found a bug? Have a feature request? Open an issue on GitHub.

Areas Where Help is Wanted

If you're looking to contribute, here are some areas where we'd love help:

  • Cross-platform testing — The codebase targets macOS, Windows, and Linux. We develop primarily on macOS and have done targeted Windows work, but need broader real-world testing on Windows (especially around the engine subprocess lifecycle, file locking, and native DLL preloading) and Linux (various distros, ARM64).

  • Integration tests / CI pipeline — Currently all tests are unit/mock-based. We need end-to-end integration tests that spin up the actual engine process with test fixture data and exercise the full MCP proxy → HTTP → engine → SQLite → search path. This would enable a proper GitHub Actions CI matrix across OS and Python versions.

  • Remove legacy workspace decode fallback — The vector search path (search.py) and FTS search path (cache.py) include fallbacks that decode base64-encoded workspace values at query time. These handle indexes created before the _decode_workspace_dir_name bug was fixed. After a couple release cycles, these become dead code and can be safely removed.

  • Migrate engine_main.py from print() to logging — The engine process uses bare print() for all status messages. Switching entire codebase to Python's logging module would give levels, timestamps, and configurable filtering while still routing through the existing log file support.

  • SIGTERM-based graceful shutdown on Windows — On Unix, stale engines receive SIGTERM before SIGKILL for graceful cleanup. Windows has no SIGTERM equivalent for non-console processes, so we use TerminateProcess directly. A Windows-native approach (e.g., named event signaling) could enable graceful shutdown there too.

Support

Found a bug? Have a feature request? Open an issue on GitHub.

License

MIT - See: LICENSE.

Attribution

Built by Farley Farley (DevOps-Nirvana), based upon Kiro Total Recall by Danilo Poccia (MIT licensed). The original session loaders, data models, and core embed/search concept originate from that project. Kiro Ception is a ground-up rewrite for production use; see the Architecture Highlights above for what's different.

Ver o original no GitHub

Bom para

Relacionados