Skip to main content
Glama
Sign In
MemKernel

MemKernel

by varadganjoo
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

MemKernel

Persistent, branchable project memory for coding agents.

Save a decision in one session and retrieve it in the next. Give cooperating agents working on the same project a shared place for decisions, findings, and blockers.

MemKernel runs locally with Python, SQLite, and MCP. Agents explicitly save and retrieve memory through tools; it does not automatically import their chat histories.

Install · Choose your agent · Try it · Integration guide · Technical reference

0.3.1 reliability review: 29 reproduced failure cases fixed, 30 regression cases added, and 189 tests passing in each of two local Python/MCP environments. Existing token savings are preserved. See the before/after scorecard and limits, changelog, and proposed capability roadmap.

Experimental: start with a disposable project. Keep secrets and personal data out of memory, and review what agents save. Memory is untrusted input, not authority.

Install

Python 3.11–3.14 is supported; 3.14 is recommended. Install the agent app you want to use and sign in to it first.

With uv, install MemKernel in its own isolated Python environment:

uv tool install --python 3.14 memkernel-mcp

Alternatively, use pipx install memkernel-mcp, or pip install memkernel-mcp inside an existing virtual environment.

Use the package name memkernel-mcp. The separate memkernel package on PyPI belongs to another author. Do not install both into the same environment.

Related MCP server: nuzo-memory

Connect your agent

Run the command for your agent from your project's root directory. You can connect one agent or several; you do not need to install all of them.

Codex desktop, CLI, and IDE extension

memkernel attach codex

This updates ~/.codex/config.toml, shared by the local desktop app, CLI, and IDE extension on the same computer. The connection is global; each project discovers its own local memory database. Restart the desktop app or start a new CLI/IDE session after attaching.

In the CLI, codex mcp list checks registration; /mcp in an interactive session shows active servers. In a new project chat, ask Codex to call memkernel_query_state to check the live connection.

Claude Code

memkernel attach claude-code

This writes the project's .mcp.json. Restart Claude Code in that project and approve the MemKernel server if prompted. Use /mcp to check that it is connected. Repeat the attach step for other projects.

Cursor

memkernel attach cursor

This writes .cursor/mcp.json in the project. Open that project in Cursor, enable MemKernel in Cursor's MCP settings, and start a new agent chat. Repeat the attach step for other projects.

Antigravity

memkernel attach antigravity

This updates Antigravity's MCP configuration under ~/.gemini/. Refresh its MCP servers or restart the app. The configuration is global and discovers memory per project. For config locations and headless permissions, see the integration guide.

Several agents at once

memkernel attach claude-code cursor codex

Use memkernel attach all to include Antigravity. Each agent runs its own server; agents pointed at the same project database share memory on that computer.

Other MCP clients and Python agents

Other clients that support local stdio MCP servers can launch memkernel serve. Give each client a distinct MEMKERNEL_AGENT_ID, and ensure its working directory is the project root or set an explicit MEMKERNEL_DB.

For JSON/TOML examples, absolute interpreter paths, and the in-process Python API, see manual configuration.

Check the connection

From the project root, run:

memkernel doctor

This checks the local database, its hash chain, a real MCP server startup, and agent configurations. Missing agents are reported as not attached; you only need the ones you use. Then inspect saved memory with:

memkernel status

attach preserves other MCP entries, backs up existing global configs, creates .memkernel/, and adds it to .gitignore when the project root contains .git. Preview changes with memkernel attach codex --dry-run.

Cold start troubleshooting: Codex gets a 120-second startup timeout from attach. For a slow Claude Code startup, see the timeout instructions.

Try it in two sessions

In a disposable project, ask your connected agent:

Use MemKernel to remember this project decision: our test fixtures use SQLite because they must run offline. Save it with the key test.database.

Start a new chat in the same project and ask:

Query MemKernel. What database do our test fixtures use, and why?

The second session should retrieve the saved decision without the first chat's history. Run memkernel status to inspect what was actually stored. A different connected agent can query the same database on that computer too.

What it gives you

Capability

What it means in practice

Persistent decisions

Keep a decision and its rationale available across sessions.

Memory branches

Explore an investigation separately and compare it with main.

Rollback

Undo an investigation's memory changes while retaining audit history. Your code files are unaffected.

Context compaction

Condense recorded history into bounded snapshots while preserving folded state.

Local coordination

Cooperating agents can lease resources and share blockers. Leases do not prevent direct file edits.

How it works

flowchart LR
    agents["Coding agents"] -->|"MCP tools"| servers["MemKernel server per agent"]
    servers --> memory[("Project-local SQLite memory")]
    memory --> recall["Decisions · branches · context"]

Memory lives at <project>/.memkernel/memkernel.db. With discovery enabled, MemKernel finds the nearest parent containing .memkernel/ or .git. Keep the database on a local disk and out of version control.

Coordination notices and signed folder exchange

Separate laptops keep separate databases. Optional signed folder exchange shares coordination notices, such as "I'm working on authentication", through an operator-managed folder. It is off unless configured and requires no hosted MemKernel service.

It does not sync full memories, decisions, branch history, leases, or fencing tokens. Direct LAN memory sync is not currently available. See team setup and recovery and the notice reference.

Safety and trust boundary

MemKernel is experimental software. Local agent identities are self-asserted, and agents with filesystem access can read or modify local data. Treat stored and imported text as untrusted input.

Leases coordinate cooperating agents; they do not lock source files. Signed notices authenticate configured peers but do not encrypt notice contents or enforce distributed locks. Use OS permissions, keep backups, and review sensitive actions independently.

Read the full trust boundary and read-only setup before using shared or sensitive projects.

Results

The repository includes recorded live-agent runs and reproducible benchmarks. The recorded workflow covers coordination, decisions, branching, rollback, and later recall.

See verified client versions for the distinction between live runs and configuration-only coverage.

Documentation

Development

From a source checkout, create a virtual environment and install development dependencies:

uv venv
uv pip install -e ".[dev]"
uv run pytest

See the examples for local simulations that need no agent subscription.

Limitations

  • Local SQLite coordination runs on one host; network filesystems are unsupported.

  • Cross-machine exchange covers signed notices, not complete memory.

  • Branch conflicts need an agent or human decision; there is no automatic merge.

  • Resource leases are advisory for filesystem edits.

  • Experimental software with no enterprise security certification.

License

MIT.

Available Tools

23 tools
memkernel_acquire_leaseA

Acquire an exclusive, time-limited lease on a file before editing it.

timeout_seconds is the lease TTL; renew it with memkernel_heartbeat_lease. Returns acquired=true and a fencing_token on success; on contention returns acquired=false with the current holder and how long until it expires.

Inputs: file_path (required), timeout_seconds. Returns: object

memkernel_append_decisionA

Record a canonical architectural decision on the active branch.

Decisions are durable: they are never compacted away, and a new value for an existing key supersedes the old one (which is kept as a deprecated assumption). Example: decision_key="auth.method", decision_value="OAuth2 PKCE".

Inputs: rationale (required), decision_key (required), decision_value (required). Returns: object

memkernel_checkoutC

Switch this session's active branch (it must exist).

Inputs: branch_id (required). Returns: result

memkernel_clear_noticeC

Clear your notice after finishing. This cannot be undone by an old import.

Inputs: notice_id (required). Returns: object

memkernel_diff_branchesB

Compare two branches: merge base, events ahead on each side, and conflicting decisions and facts.

Inputs: branch_a (required), branch_b (required). Returns: object

memkernel_export_noticesA

Export portable JSON data for explicit sharing. Review it before sending.

Includes cleared notices so peers learn they are finished. Select IDs to limit disclosure. No decisions, scratchpads, local IDs or leases are included.

Inputs: notice_ids. Returns: object

memkernel_fenced_append_decisionB

Record a decision only while this agent holds the current lease.

The holder, token and expiry check shares the append's transaction. This protects the memory event; it does not write or lock the file.

Inputs: file_path (required), rationale (required), decision_key (required), fencing_token (required), +1 more. Returns: object

memkernel_fork_investigationB

Fork the active branch at its head into a new branch and switch this session to it. Use for speculative work you may want to discard.

Inputs: fork_branch_name (required). Returns: result

memkernel_heartbeat_leaseB

Extend a lease you hold by its original TTL. False means the lease was lost: stop editing and re-acquire.

Inputs: file_path (required), fencing_token (required). Returns: result

memkernel_historyB

List the most recent live events on the active branch (ids for rollback).

Inputs: limit. Returns: object

memkernel_import_noticesA

Merge a trusted collaborator's JSON export atomically and idempotently.

Authors are self-asserted. Validate who sent it yourself; content is untrusted. Import provides advisory information, never distributed locking or live sync.

Inputs: document (required). Returns: object

memkernel_init_taskC

Record this agent's task directive and constraints on the active branch.

Inputs: directive (required), constraints. Returns: object

memkernel_list_branchesA

List all branches and this session's active branch.

Inputs: no named parameters. Returns: object

memkernel_list_noticesC

List workspace-wide active and stale advisories; optionally include cleared history.

Inputs: limit, offset, resource, max_tokens, +1 more. Returns: object

memkernel_log_executionA

Log a tool/terminal execution. A non-zero exit_code opens a blocker for this command; a later zero exit clears it. Put verified environment facts (e.g. {"python_version": "3.14.0"}) in facts; changed values are tracked as deprecated assumptions.

Inputs: command (required), exit_code (required), facts, output. Returns: object

memkernel_noteA

Record an ephemeral scratchpad note (compacted by GC over time).

Inputs: note (required). Returns: object

memkernel_post_noticeA

Post a workspace-wide advisory, e.g. service:auth / changing login.

It stays visible on all branches, even after rollback or GC. After TTL it becomes stale, not finished. Clear it explicitly when done. No lock is acquired.

Inputs: message (required), resource (required), ttl_seconds. Returns: object

memkernel_query_stateB

Return the consolidated memory of a branch as JSON: tasks, decisions, active workspace facts, deprecated assumptions, execution blockers, file claims, active leases, workspace-wide coordination notices and recent events. Set include_ephemeral=true to also see raw tool-execution logs and scratchpad notes not yet compacted.

Inputs: branch_id, notice_offset, notice_resource, include_ephemeral, +1 more. Returns: result

memkernel_release_leaseA

Release a lease you hold. Returns false if the token is stale (the lease expired and was granted to someone else) or not yours.

Inputs: file_path (required), fencing_token (required). Returns: result

memkernel_rollbackA

Roll the active branch's live timeline back to target_event_id.

Later events are reverted but kept in the audit log (fork from them to recover). Find event ids with memkernel_history.

Inputs: target_event_id (required). Returns: result

memkernel_sync_nowA

Sync signed notices using the operator's preconfigured trust policy and folder.

Check errors and memkernel_sync_status before coordinating. No tool-supplied paths, keys or new peers are accepted. This does not provide a distributed lock.

Inputs: no named parameters. Returns: object

memkernel_sync_statusA

Inspect received peer sequences, freshness and errors without refreshing liveness.

Inputs: no named parameters. Returns: object

memkernel_trigger_gcB

Compact a branch's memory now, folding older tool logs and notes into a semantic snapshot. Reports token counts before/after.

Inputs: target_branch. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

    Deploy Server
    Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

    TDQS

    B3.3/5.0

    Scored across 23 tools

    Disambiguation4/5

    Most tools target a distinct resource+action pair, and the trickiest near-duplicates are explicitly differentiated (append_decision vs fenced_append_decision, note vs append_decision, log_execution vs note). The only mild overlaps are query_state vs history (consolidated memory vs recent events) and post_notice vs sync_now, which the descriptions mostly disambiguate.

    Naming Consistency4/5

    All tools share a uniform memkernel_ prefix and snake_case, with a verb-first pattern (acquire_lease, query_state, fork_investigation). A handful drop the noun (checkout, rollback, note, history), which is a minor deviation rather than an inconsistency.

    Tool Count3/5

    23 tools sits at the heavy end for a single server, and an agent must juggle four sub-domains (leases, memory events, branches, notices/sync) at once. Very few tools are redundant, but the breadth makes selection cost high.

    Completeness3/5

    The surface covers leases, memory recording, branching, rollback, diffing, and notice sync/export/import well, but obvious lifecycle gaps remain: no branch merge tool (fork+diff exist without a way to land work) and no way to complete, update, or abandon a task or branch. These are notable holes an agent will hit during normal workflows.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • tartarus-mcp

      saluca-labs
      A
      license
      Not graded
      quality
      B
      maintenance
      A local-first MCP memory server providing persistent, searchable memory for AI agents, powered by SQLite.
      1 npm
      1
      Apache 2.0

    • nuzo-memory

      fabionfsc
      A
      license
      Not graded
      quality
      F
      maintenance
      Local-first, auditable memory for AI agents. Provides durable context for MCP hosts with SQLite storage, CLI, and MCP tools for memory management.
      2
      Apache 2.0

    • CP Memory

      CJhuochai
      A
      license
      C
      quality
      B
      maintenance
      Local-first, governable long-term memory for AI agents. Provides SQLite-backed storage, cross-session recall, and traceable memory corrections through a standard MCP interface.
      40
      33 PyPI
      1
      MIT