Your project, remembered.

One service. Two ways in.

MemKernel is a code-aware memory service for AI coding copilots. Use its MCP server from a compatible client, or embed the Python library in your own agent harness. Both use the same MemoryService, assembled through build_service().

Memories are stored locally in ChromaDB by default. Retrieval combines dense embeddings and BM25 with reciprocal rank fusion, then ranks results using relevance, recency, and importance. Recall returns lightweight references so the agent can decide what to load.

Installation

Use Python 3.11, 3.12, or 3.13. Create and activate a virtual environment before installing.

python3 -m venv .venv
source .venv/bin/activate
python -m pip install memkernel

On Windows PowerShell, activate the environment with .venv\Scripts\Activate.ps1, then run the same pip command.

# In an activated environment with uv installed
uv pip install memkernel

# Or add the dependency to a Poetry project
poetry add memkernel

The installed memkernel command starts an MCP server over stdio by default. For an in-process integration, use the Python entry point below.

Connect Claude Code

1. Register the server

From your project directory, run this command with the MemKernel environment active:

claude mcp add \
  --scope project \
  --env MEMKERNEL_PROJECT_ID=my-project \
  --transport stdio \
  memkernel -- memkernel

Replace my-project with your project identifier. The command writes project-scoped configuration to .mcp.json. Alternatively, merge this entry into that file at the project root:

{
  "mcpServers": {
    "memkernel": {
      "type": "stdio",
      "command": "memkernel",
      "args": [],
      "env": {
        "MEMKERNEL_PROJECT_ID": "my-project"
      }
    }
  }
}

The memkernel executable must be on the client process's PATH. Activate the virtual environment before launching Claude Code, or use the executable's absolute path in command. Launch Claude Code, approve the project server when prompted, and use /mcp to check its status.

Client configuration follows the official Claude Code MCP documentation. Other MCP clients use the same server command and environment variables in their own configuration format.

2. Teach the agent when to remember

Add the repository's memory instructions template to your project's CLAUDE.md. The template describes when to recall, retain, checkpoint, promote, and use document memory.

3. Add lifecycle hooks when useful

The hook templates cover session start, before compaction, and after compaction. Follow each script's prerequisites and register hooks in .claude/settings.json. See the lifecycle section for the corresponding in-process component.

Connect Kiro

Give Kiro persistent project memory through MemKernel's stdio MCP server. The Kiro integration templates, added in commit 6a4d51d, combine server settings, always-on memory instructions, and lifecycle hooks.

1. Install an executable Kiro can find

With Python 3.11–3.13 and either pipx or uv installed, choose one installation method:

pipx install memkernel
# Or: uv tool install memkernel

which memkernel

Kiro's desktop process may have a different PATH from your shell. If startup fails, replace command below with the full executable path returned by which memkernel. On Windows, use where.exe memkernel.

2. Register the MCP server

Merge this into .kiro/settings/mcp.json in your project. Keep any existing server entries. For all workspaces, use ~/.kiro/settings/mcp.json instead.

{
  "mcpServers": {
    "memkernel": {
      "command": "memkernel",
      "args": [],
      "env": {
        "MEMKERNEL_PROJECT_ID": "my-project",
        "MEMKERNEL_CHROMA_PERSIST_PATH": "${HOME}/.memkernel/my-project"
      },
      "disabled": false,
      "autoApprove": ["recall", "get", "ask", "retain", "consolidate"]
    }
  }
}

• Change my-project in both values to your project's identifier and data directory. Keep the same values across sessions.
• Use an absolute storage path. The template expands your home directory; approve that variable in Kiro if prompted, or replace it with a literal absolute path. The default relative path can otherwise point somewhere unexpected when launched by an IDE.
• The template's autoApprove list allows recall, get, ask, retain, and consolidate without a tool prompt. Edit this list to suit your workflow; the four other MemKernel tools are not pre-approved by this entry.

Save the file and check the server in Kiro's MCP panel. See Kiro's MCP configuration reference. To share a running local HTTP server instead, use the HTTP server quickstart and a url entry for http://127.0.0.1:8765/mcp.

3. Add the memory steering file

Copy the full memory steering template to .kiro/steering/memory.md. Keep its YAML front matter at the very beginning:

---
inclusion: always
---

The rest of the template tells Kiro to recover checkpoints, retain task state and durable knowledge, consolidate candidates, and use document memory and the wiki bridge. The server provides the tools; these instructions make remembering part of the agent's workflow.

4. Add lifecycle hooks

For Kiro IDE 1.x and CLI V3, save this adapted template as .kiro/hooks/memkernel.json. It gives each hook a name, as required by the current hook schema.

{
  "version": "v1",
  "hooks": [
    {
      "name": "memkernel: recall context",
      "trigger": "SessionStart",
      "action": {
        "type": "agent",
        "prompt": "Using the memkernel MCP server: call recall(query=\"session checkpoint\", checkpoint_only=true, top_k=3) and recall(query=\"<current task>\", tier=\"long_term\", top_k=8). If the project has a wiki (MEMKERNEL_WIKI_DIR), read its index.md. Summarise what is relevant in three lines, then continue with the user's request."
      }
    },
    {
      "name": "memkernel: retain progress",
      "trigger": "Stop",
      "action": {
        "type": "agent",
        "prompt": "Before finishing: if this turn produced a decision, convention, fact or procedure that holds beyond this session, retain it in memkernel with that type (one idea per memory; use supersedes=<old ref_id> when it replaces an earlier one). If the plan or task state changed, retain(type=\"task\", content=\"Goal: ... Next: ... Open: ...\"). Do nothing if there is nothing worth keeping."
      }
    }
  ]
}

The Stop hook runs after every turn and adds token usage. Remove it if session-start recall and occasional checkpoints suit your workflow better.

Using MemKernel, save a checkpoint episode with checkpoint=true.
Summarize what is done, the current task, next steps, and open questions.
Then call consolidate() and promote useful candidates into durable memories.

Kiro CLI custom agents

For a custom profile in .kiro/agents/<name>.json, use includeMcpJson: true to load the workspace server, or put its entry directly in mcpServers. Add file://.kiro/steering/memory.md to resources if you manage context explicitly. Current profiles inherit default steering unless that inheritance is disabled. Check the agent configuration reference for your CLI version.

Legacy Amazon Q Developer CLI uses ~/.aws/amazonq/mcp.json for the same MCP server entry. Its agent hooks use older names such as agentSpawn and stop; do not mix the old profile format with the standalone v1 hook file above.

Check the connection

Ask Kiro to retain a small test fact, then recall it from a new session using the same project ID and storage path. If startup is slow, allow the local embedding model's first download to finish. If recall is empty, check both environment values before changing the memory protocol.

Use the Python library

build_service() is the supported entry point. Configuration is read from MEMKERNEL_* environment variables or a .env file.

import os
from memkernel.factory import build_service
from memkernel.core.models import MemoryType

os.environ["MEMKERNEL_PROJECT_ID"] = "my-project"
memory = build_service()

ref_id = memory.retain(
    "Use PostgreSQL for transactional inventory updates.",
    MemoryType.DECISION,
    tags=["architecture", "database"],
)

for ref in memory.recall("database choice", top_k=5):
    print(ref.ref_id, ref.tier, ref.preview)

# Fetch the complete decision when needed.
decision = memory.get(ref_id)
print(decision.content if decision else "Memory not found")

retain() returns a reference ID. Storing identical content with the same type is idempotent. recall() returns ArtifactRef objects rather than full memory bodies.

For a newer decision, retain the replacement with supersedes=ref_id. The replaced memory is hidden from recall. For a permanent deletion, call forget(ref_id).

Memory types & tiers

The memory type determines the tier and default retention policy. Durable memories do not expire; short-lived memories can be reinforced through recall and promoted when they prove useful.

For expiring memories, the retention window grows with access count: base_ttl × (1 + access_boost × access_count), measured from the later of creation and last access. The default access boost is 0.5.

Consolidate, then promote

consolidate() purges expired memories and returns promotion candidates. The caller supplies the distilled content to promote(); provenance is retained through promoted_from. Consolidation does not automatically turn every observation into a durable fact.

MCP tool reference

Version 0.3.0 exposes nine MCP tools. The signatures below show MCP parameter names; the Python service uses MemoryType and MemoryTier enums where applicable.

9 of 9 tools

No tools match. Try “memory”, “document”, or “wiki”.

Store the document. Ask for context.

The document memory type stores the body separately from its summary and indexes text chunks for retrieval. Use it for large specs, transcripts, or other artifacts.

from pathlib import Path
from memkernel.factory import build_service
from memkernel.core.models import MemoryType

memory = build_service()
spec = Path("specs/auth.md")
ref_id = memory.retain(
    spec.read_text(encoding="utf-8"),
    MemoryType.DOCUMENT,
    source=str(spec),
)

result = memory.ask(
    ref_id,
    "Which endpoints need rate limiting?",
    mode="auto",
)
if result is not None:
    print(result.answer)

Create the example input file specs/auth.md first, or replace that path with an existing document.

• Local reasoner (default): returns the most relevant document chunks using dense retrieval, BM25, and RRF. It does not generate an LLM answer and reports mode="rag".
• RLM Studio (optional): delegates to an external reasoner with direct, rag, rlm, or auto. Install and configure it separately, then set MEMKERNEL_REASONER=rlmstudio. If the package is not importable, MemKernel logs a warning and falls back to the local reasoner.

Keep continuity across sessions

Using Kiro? Start with the Kiro steering and lifecycle setup for session recall, progress retention, and checkpoints.

MemoryLifecycle packages the session protocol for an in-process harness. Its methods return Markdown suitable for injecting into the agent's context.

from memkernel.factory import build_service
from memkernel.lifecycle import MemoryLifecycle

lifecycle = MemoryLifecycle(build_service())

# Inject this at the beginning of a session.
context = lifecycle.on_session_start()

# Before your harness compacts its context:
lifecycle.on_pre_compact("Your checkpoint summary")

# Re-inject after compaction:
recovered = lifecycle.on_post_compact()

# At the end of the session:
lifecycle.on_session_end("Your final session summary")

Supply a meaningful checkpoint summary from the harness at each event. Calling these methods alone does not inject anything into an agent; your harness owns that step.

A human-readable memory layer

The wiki bridge connects long-term memories with a Markdown knowledge base that you can review and version in Git.

1. Set MEMKERNEL_WIKI_DIR, for example to knowledge/wiki, or pass wiki_dir to the MCP tools.
2. Run wiki_export to generate draft pages with source citations. Existing pages are not overwritten.
3. Review and edit the drafts, and commit curated pages to your repository.
4. Run wiki_import so recall can find the reviewed knowledge. Changed pages supersede their earlier memory.

Exported pages use the LLM Wiki pattern, with an index, a log, typed pages, and memkernel:// source references.

Configuration

Settings are read from environment variables with the MEMKERNEL_ prefix, or a .env file. These are the most commonly changed defaults.

The default persistence path is relative to the server's working directory. Set an absolute MEMKERNEL_CHROMA_PERSIST_PATH when you want multiple entry points to share a known local store.

MEMKERNEL_PROJECT_ID=my-project \
MEMKERNEL_TRANSPORT=streamable-http \
memkernel

# MCP endpoint: http://127.0.0.1:8765/mcp

Keep local servers bound to localhost unless you have configured the necessary network access controls for your deployment. Project namespaces separate stored memories; they are not a user authentication system.

Troubleshooting

Build with us

MemKernel is open source under Apache-2.0. Bugs, reproducible examples, and improvements to integrations or documentation are welcome in the repository.

The core API guide describes MemKernel 0.3.0, checked on October 12, 2026. Kiro setup was added on October 13 from commit 6a4d51d and checked against Kiro’s current documentation. The Kiro templates are repository additions, not a new package release. For newer changes, consult the release notes.