MemCtrl v1.3.0 — Reliability Foundation & Evidence-Linked Memory Lifecycle

Overview

Major reliability and knowledge lifecycle release. Upgrades MemCtrl from observable memory infrastructure into a reviewable, evidence-linked agent memory system with an explicit knowledge lifecycle, immutable provenance, and measurable history reuse.

What's New

P0 Reliability & Storage Foundation

• Centralized Persistence Boundary — All memory insertions (manual, extractor, reflection, MCP, adapters) route through _insert_memory_tx() with mandatory secret sanitization (sanitize_text()) before hitting SQLite.
• Expiry as Eligibility — Memory expiration now controls retrieval eligibility (expires_at < now filtered by default across get, list, query, tree, and reflection inputs) rather than depending solely on physical deletion.
• Scope-Isolated Query Cache — QueryCacheKey parameterizes cache identity across query, layer, retrieval_version, and model_identity, preventing cross-layer result leakage in both in-memory and SQLite cache.
• Immutable Creation Timestamps — created_at is strictly immutable. Introduced updated_at, last_accessed_at, and access_count in schema v3; decoupled retrieval access telemetry from evidential reinforcement.
• Durable Decay Scheduling — Maintenance execution state is persisted in SQLite maintenance_state across process restarts. Aligned floor review detection with clamp semantics (confidence <= floor is review-eligible).
• Diagnostic Decoupling — Health checks (memctrl doctor) distinguish source attribution from verification and report retrieval_exposure instead of calling query trace appearances "provenance coverage".

Knowledge Lifecycle & Lineage (Schema v4)

• Orthogonal Semantic Axes — Distinguishes what was asserted vs what was verified:
  • claim_type: observation, assertion, hypothesis, decision, derived_lesson
  • lifecycle_state: candidate, accepted, superseded, rejected, archived
  • verification_state: unverified, supported, disputed, refuted
  • Temporal bounds: observed_at, valid_from, valid_until
• Memory Relations — Table memory_relations records directed lineage (derived_from, supports, contradicts, supersedes, refutes). Distinguishes temporal replacement (supersede_memory()) from empirical refutation (refute_memory()).
• External Evidence References — Table memory_evidence connects memories to authoritative external records (e.g. task IDs, commit SHAs) without mutating or copying authority.
• Automated Database Migration — Safe, idempotent migration path from v2 through v3 to v4 with legacy semantics preserved.

Reflection as Candidate Generation

• Preserved Session Evidence — Session-end reflection preserves session source records in the session layer instead of bulk-promoting them into project truth.
• Reviewable Candidates — Reflection output is stored as reviewable candidate knowledge (lifecycle_state='candidate', verification_state='unverified') linked to source memories via derived_from relations.

Review Workflow (CLI & MCP)

• CLI Commands — Added candidates, show <id>, accept <id>, reject <id>, history <id>, dispute <id>, and refute <id> --reason <reason>. Guards against accepting refuted claims or creating self-referencing cycles.
• MCP Tools — Added memctrl_candidates and memctrl_review tools for agent-native memory curation.

Lifecycle-Aware Retrieval

• Allowlist-Based Filtering — Default retrieval strictly requires lifecycle_state == 'accepted', verification_state != 'refuted', and non-expired status.
• Annotated History Mode — history=True retrieval surfaces historical facts with explicit visual annotations ([REFUTED], [SUPERSEDED], [CANDIDATE], [ARCHIVED]).

Read-Only Heli History Adapter & Evaluation

• Read-Only Source Adapter — HeliSourceAdapter inspects completed Heli-Harness workspace tasks without modifying any files under .heli-harness.
• Lesson Distiller — HeliDistiller extracts reusable candidate lessons, links external evidence, and captures counterexamples across tasks with similar symptoms.
• CLI Review Command — memctrl review heli --workspace <path> --completed <n> [--dry-run|--persist].
• Pilot Evaluation Benchmark — An initial read-only Heli-history evaluation across 20 completed tasks returned useful leads for all 12 benchmark queries, compared with 11/12 for the grep baseline, while correctly identifying the benchmark's refuted hypothesis. This represents pilot validation evidence on a curated historical corpus, not a general uncurated recall benchmark.

Explicit Non-Goals

• No Connectra changes or dependencies.
• No Heli-Harness source modifications.
• Heli integration is strictly read-only.
• No embeddings or vector databases added.
• No graph database runtime introduced.
• No shared cross-session memory authority.

MemCtrl v1.2.1 — Credibility Hardening

What's New

Benchmarks & Trust

• Honest capability benchmark replaces misleading precision claims
• Retrieval precision fixed: synonym expansion, layer boost, confidence weighting, relative threshold filtering

CLI Polish

• Starting MCP server
  Use Ctrl+C to stop no longer shows fake port/host args
• Package description aligned with v1.2 positioning

Durability

• All 19 SQLite write paths wrapped with exponential backoff retry
• Tree LLM clustering batched to 20 memories per prompt

Docs & Demos

• New migration demo: +-------------------------------------------------------------------+
  | MemCtrl Migration Demo |
  | Your Agent's Memory Travels With You |
  | --- |
  | Watch project context move seamlessly from Claude Code to Cursor. |
  +-------------------------------------------------------------------+
  ----------------------- PHASE 1: Coding in Claude Code ------------------------
  +-------------------------------- Claude Code --------------------------------+
  | I'm reviewing the auth system. Let me store what I learn so I don't have to |
  | rediscover it in the next session. |
  +-----------------------------------------------------------------------------+
• OTel memory spec submitted to OpenTelemetry GenAI SIG

Install

Requirement already satisfied: memctrl in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (1.2.0)
Requirement already satisfied: mcp>=1.0.0 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from memctrl) (1.27.1)
Requirement already satisfied: python-dotenv>=1.0.0 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from memctrl) (1.0.1)
Requirement already satisfied: rich>=13.0.0 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from memctrl) (15.0.0)
Requirement already satisfied: typer>=0.12.0 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from memctrl) (0.24.2)
Requirement already satisfied: watchdog>=4.0.0 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from memctrl) (6.0.0)
Requirement already satisfied: anyio>=4.5 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from mcp>=1.0.0->memctrl) (4.13.0)
Requirement already satisfied: httpx-sse>=0.4 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from mcp>=1.0.0->memctrl) (0.4.3)
Requirement already satisfied: httpx<1.0.0,>=0.27.1 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from mcp>=1.0.0->memctrl) (0.28.1)
Requirement already satisfied: jsonschema>=4.20.0 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from mcp>=1.0.0->memctrl) (4.26.0)
Requirement already satisfied: pydantic-settings>=2.5.2 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from mcp>=1.0.0->memctrl) (2.7.0)
Requirement already satisfied: pydantic<3.0.0,>=2.11.0 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from mcp>=1.0.0->memctrl) (2.13.4)
Requirement already satisfied: pyjwt>=2.10.1 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from pyjwt[crypto]>=2.10.1->mcp>=1.0.0->memctrl) (2.13.0)
Requirement already satisfied: python-multipart>=0.0.9 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from mcp>=1.0.0->memctrl) (0.0.29)
Requirement already satisfied: pywin32>=310 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from mcp>=1.0.0->memctrl) (311)
Requirement already satisfied: sse-starlette>=1.6.1 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from mcp>=1.0.0->memctrl) (3.4.4)
Requirement already satisfied: starlette>=0.27 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from mcp>=1.0.0->memctrl) (1.0.1)
Requirement already satisfied: typing-extensions>=4.9.0 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from mcp>=1.0.0->memctrl) (4.15.0)
Requirement already satisfied: typing-inspection>=0.4.1 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from mcp>=1.0.0->memctrl) (0.4.2)
Requirement already satisfied: uvicorn>=0.31.1 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from mcp>=1.0.0->memctrl) (0.34.0)
Requirement already satisfied: certifi in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from httpx<1.0.0,>=0.27.1->mcp>=1.0.0->memctrl) (2026.4.22)
Requirement already satisfied: httpcore==1.* in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from httpx<1.0.0,>=0.27.1->mcp>=1.0.0->memctrl) (1.0.9)
Requirement already satisfied: idna in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from httpx<1.0.0,>=0.27.1->mcp>=1.0.0->memctrl) (3.13)
Requirement already satisfied: h11>=0.16 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from httpcore==1.*->httpx<1.0.0,>=0.27.1->mcp>=1.0.0->memctrl) (0.16.0)
Requirement already satisfied: annotated-types>=0.6.0 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from pydantic<3.0.0,>=2.11.0->mcp>=1.0.0->memctrl) (0.7.0)
Requirement already satisfied: pydantic-core==2.46.4 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from pydantic<3.0.0,>=2.11.0->mcp>=1.0.0->memctrl) (2.46.4)
Requirement already satisfied: attrs>=22.2.0 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from jsonschema>=4.20.0->mcp>=1.0.0->memctrl) (26.1.0)
Requirement already satisfied: jsonschema-specifications>=2023.03.6 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from jsonschema>=4.20.0->mcp>=1.0.0->memctrl) (2025.9.1)
Requirement already satisfied: referencing>=0.28.4 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from jsonschema>=4.20.0->mcp>=1.0.0->memctrl) (0.37.0)
Requirement already satisfied: rpds-py>=0.25.0 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from jsonschema>=4.20.0->mcp>=1.0.0->memctrl) (0.30.0)
Requirement already satisfied: cryptography>=3.4.0 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from pyjwt[crypto]>=2.10.1->mcp>=1.0.0->memctrl) (48.0.0)
Requirement already satisfied: cffi>=2.0.0 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from cryptography>=3.4.0->pyjwt[crypto]>=2.10.1->mcp>=1.0.0->memctrl) (2.0.0)
Requirement already satisfied: pycparser in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from cffi>=2.0.0->cryptography>=3.4.0->pyjwt[crypto]>=2.10.1->mcp>=1.0.0->memctrl) (3.0)
Requirement already satisfied: markdown-it-py>=2.2.0 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from rich>=13.0.0->memctrl) (4.0.0)
Requirement already satisfied: pygments<3.0.0,>=2.13.0 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from rich>=13.0.0->memctrl) (2.20.0)
Requirement already satisfied: mdurl~=0.1 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from markdown-it-py>=2.2.0->rich>=13.0.0->memctrl) (0.1.2)
Requirement already satisfied: click>=8.2.1 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from typer>=0.12.0->memctrl) (8.3.3)
Requirement already satisfied: shellingham>=1.3.0 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from typer>=0.12.0->memctrl) (1.5.4)
Requirement already satisfied: annotated-doc>=0.0.2 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from typer>=0.12.0->memctrl) (0.0.4)
Requirement already satisfied: colorama in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from click>=8.2.1->typer>=0.12.0->memctrl) (0.4.6)

Full Changelog

v1.2.0...v1.2.1

MemCtrl v1.2.0 — Observable Memory Infrastructure

MemCtrl v1.2.0 — Observable Memory Infrastructure for AI Agents

Phase 2: Agent Runtime

• Confidence Decay — Inferred facts decay over time if not reinforced; explicit facts persist
• Query Result Cache — Repeat queries return in <1ms (was 50-500ms)
• Reflection Engine — Auto-detect session end via git commit, time-based, or explicit
• Incremental Tree Rebuild — Only rebuild affected branches, not the entire tree
• Project-Local Database — Each project gets its own

Phase 3: Observability

• Retrieval Provenance — Full audit trail for every retrieval: source, confidence, match reason, trace path
• OpenTelemetry Exporter — First reference implementation for conventions
• Memory Span — Context manager for operation tracing across agent tasks

New Commands

• — Explicit session end → immediate consolidation
• — Check heuristics → consolidate if any fire
• — Export memory spans to JSON
• — Show memory operation statistics

Tests

468 passing, 2 skipped

Upgrade

Requirement already satisfied: memctrl in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (1.0.1)
Collecting memctrl
Downloading memctrl-1.1.0-py3-none-any.whl.metadata (11 kB)
Requirement already satisfied: mcp>=1.0.0 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from memctrl) (1.27.1)
Requirement already satisfied: python-dotenv>=1.0.0 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from memctrl) (1.0.1)
Requirement already satisfied: rich>=13.0.0 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from memctrl) (15.0.0)
Requirement already satisfied: typer>=0.12.0 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from memctrl) (0.24.2)
Requirement already satisfied: watchdog>=4.0.0 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from memctrl) (6.0.0)
Requirement already satisfied: anyio>=4.5 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from mcp>=1.0.0->memctrl) (4.13.0)
Requirement already satisfied: httpx-sse>=0.4 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from mcp>=1.0.0->memctrl) (0.4.3)
Requirement already satisfied: httpx<1.0.0,>=0.27.1 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from mcp>=1.0.0->memctrl) (0.28.1)
Requirement already satisfied: jsonschema>=4.20.0 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from mcp>=1.0.0->memctrl) (4.26.0)
Requirement already satisfied: pydantic-settings>=2.5.2 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from mcp>=1.0.0->memctrl) (2.7.0)
Requirement already satisfied: pydantic<3.0.0,>=2.11.0 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from mcp>=1.0.0->memctrl) (2.13.4)
Requirement already satisfied: pyjwt>=2.10.1 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from pyjwt[crypto]>=2.10.1->mcp>=1.0.0->memctrl) (2.13.0)
Requirement already satisfied: python-multipart>=0.0.9 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from mcp>=1.0.0->memctrl) (0.0.29)
Requirement already satisfied: pywin32>=310 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from mcp>=1.0.0->memctrl) (311)
Requirement already satisfied: sse-starlette>=1.6.1 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from mcp>=1.0.0->memctrl) (3.4.4)
Requirement already satisfied: starlette>=0.27 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from mcp>=1.0.0->memctrl) (1.0.1)
Requirement already satisfied: typing-extensions>=4.9.0 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from mcp>=1.0.0->memctrl) (4.15.0)
Requirement already satisfied: typing-inspection>=0.4.1 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from mcp>=1.0.0->memctrl) (0.4.2)
Requirement already satisfied: uvicorn>=0.31.1 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from mcp>=1.0.0->memctrl) (0.34.0)
Requirement already satisfied: certifi in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from httpx<1.0.0,>=0.27.1->mcp>=1.0.0->memctrl) (2026.4.22)
Requirement already satisfied: httpcore==1.* in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from httpx<1.0.0,>=0.27.1->mcp>=1.0.0->memctrl) (1.0.9)
Requirement already satisfied: idna in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from httpx<1.0.0,>=0.27.1->mcp>=1.0.0->memctrl) (3.13)
Requirement already satisfied: h11>=0.16 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from httpcore==1.*->httpx<1.0.0,>=0.27.1->mcp>=1.0.0->memctrl) (0.16.0)
Requirement already satisfied: annotated-types>=0.6.0 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from pydantic<3.0.0,>=2.11.0->mcp>=1.0.0->memctrl) (0.7.0)
Requirement already satisfied: pydantic-core==2.46.4 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from pydantic<3.0.0,>=2.11.0->mcp>=1.0.0->memctrl) (2.46.4)
Requirement already satisfied: attrs>=22.2.0 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from jsonschema>=4.20.0->mcp>=1.0.0->memctrl) (26.1.0)
Requirement already satisfied: jsonschema-specifications>=2023.03.6 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from jsonschema>=4.20.0->mcp>=1.0.0->memctrl) (2025.9.1)
Requirement already satisfied: referencing>=0.28.4 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from jsonschema>=4.20.0->mcp>=1.0.0->memctrl) (0.37.0)
Requirement already satisfied: rpds-py>=0.25.0 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from jsonschema>=4.20.0->mcp>=1.0.0->memctrl) (0.30.0)
Requirement already satisfied: cryptography>=3.4.0 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from pyjwt[crypto]>=2.10.1->mcp>=1.0.0->memctrl) (48.0.0)
Requirement already satisfied: cffi>=2.0.0 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from cryptography>=3.4.0->pyjwt[crypto]>=2.10.1->mcp>=1.0.0->memctrl) (2.0.0)
Requirement already satisfied: pycparser in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from cffi>=2.0.0->cryptography>=3.4.0->pyjwt[crypto]>=2.10.1->mcp>=1.0.0->memctrl) (3.0)
Requirement already satisfied: markdown-it-py>=2.2.0 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from rich>=13.0.0->memctrl) (4.0.0)
Requirement already satisfied: pygments<3.0.0,>=2.13.0 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from rich>=13.0.0->memctrl) (2.20.0)
Requirement already satisfied: mdurl~=0.1 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from markdown-it-py>=2.2.0->rich>=13.0.0->memctrl) (0.1.2)
Requirement already satisfied: click>=8.2.1 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from typer>=0.12.0->memctrl) (8.3.3)
Requirement already satisfied: shellingham>=1.3.0 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from typer>=0.12.0->memctrl) (1.5.4)
Requirement already satisfied: annotated-doc>=0.0.2 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from typer>=0.12.0->memctrl) (0.0.4)
Requirement already satisfied: colorama in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from click>=8.2.1->typer>=0.12.0->memctrl) (0.4.6)
Downloading memctrl-1.1.0-py3-none-any.whl (36 kB)
Installing collected packages: memctrl
Attempting uninstall: memctrl
Found existing installation: memctrl 1.0.1
Uninstalling memctrl-1.0.1:
Successfully uninstalled memctrl-1.0.1
Successfully installed memctrl-1.1.0

MemCtrl v1.1.0

What's New

Features

• Project-local database isolation: Each project now gets its own instead of sharing a global database. Run Created .memoryrc in any project to get isolated memory.
• Kimi support: [memctrl] Unknown tool: kimi
  [memctrl] No tools detected. Install paths checked:
  claude_code: ~/.claude/agent/skills/memctrl/SKILL.md
  claude_code: .claude/agent/skills/memctrl/SKILL.md
  cursor: ~/.cursor/skills/memctrl/SKILL.md
  cursor: .cursor/skills/memctrl/SKILL.md
  codex: ~/.codex/skills/memctrl/SKILL.md
  axga: ~/.axga/agent/skills/memctrl/SKILL.md
  pi: ~/.pi/agent/skills/memctrl/SKILL.md

To force install for a specific tool, use:
memctrl install --tool claude_code

No tools installed. See paths above. now works for Kimi Code CLI users.

• Mandatory SKILL.md protocol: Rewritten as active/mandatory instructions so AI assistants auto-use memctrl without prompting.

Fixes

• README install commands corrected ( → )
• CI lint/format errors resolved

Upgrade

Requirement already satisfied: memctrl in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (1.0.0)
Collecting memctrl
Downloading memctrl-1.0.1-py3-none-any.whl.metadata (11 kB)
Requirement already satisfied: mcp>=1.0.0 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from memctrl) (1.27.1)
Requirement already satisfied: python-dotenv>=1.0.0 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from memctrl) (1.0.1)
Requirement already satisfied: rich>=13.0.0 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from memctrl) (15.0.0)
Requirement already satisfied: typer>=0.12.0 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from memctrl) (0.24.2)
Requirement already satisfied: watchdog>=4.0.0 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from memctrl) (6.0.0)
Requirement already satisfied: anyio>=4.5 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from mcp>=1.0.0->memctrl) (4.13.0)
Requirement already satisfied: httpx-sse>=0.4 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from mcp>=1.0.0->memctrl) (0.4.3)
Requirement already satisfied: httpx<1.0.0,>=0.27.1 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from mcp>=1.0.0->memctrl) (0.28.1)
Requirement already satisfied: jsonschema>=4.20.0 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from mcp>=1.0.0->memctrl) (4.26.0)
Requirement already satisfied: pydantic-settings>=2.5.2 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from mcp>=1.0.0->memctrl) (2.7.0)
Requirement already satisfied: pydantic<3.0.0,>=2.11.0 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from mcp>=1.0.0->memctrl) (2.13.4)
Requirement already satisfied: pyjwt>=2.10.1 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from pyjwt[crypto]>=2.10.1->mcp>=1.0.0->memctrl) (2.13.0)
Requirement already satisfied: python-multipart>=0.0.9 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from mcp>=1.0.0->memctrl) (0.0.29)
Requirement already satisfied: pywin32>=310 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from mcp>=1.0.0->memctrl) (311)
Requirement already satisfied: sse-starlette>=1.6.1 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from mcp>=1.0.0->memctrl) (3.4.4)
Requirement already satisfied: starlette>=0.27 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from mcp>=1.0.0->memctrl) (1.0.1)
Requirement already satisfied: typing-extensions>=4.9.0 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from mcp>=1.0.0->memctrl) (4.15.0)
Requirement already satisfied: typing-inspection>=0.4.1 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from mcp>=1.0.0->memctrl) (0.4.2)
Requirement already satisfied: uvicorn>=0.31.1 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from mcp>=1.0.0->memctrl) (0.34.0)
Requirement already satisfied: certifi in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from httpx<1.0.0,>=0.27.1->mcp>=1.0.0->memctrl) (2026.4.22)
Requirement already satisfied: httpcore==1.* in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from httpx<1.0.0,>=0.27.1->mcp>=1.0.0->memctrl) (1.0.9)
Requirement already satisfied: idna in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from httpx<1.0.0,>=0.27.1->mcp>=1.0.0->memctrl) (3.13)
Requirement already satisfied: h11>=0.16 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from httpcore==1.*->httpx<1.0.0,>=0.27.1->mcp>=1.0.0->memctrl) (0.16.0)
Requirement already satisfied: annotated-types>=0.6.0 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from pydantic<3.0.0,>=2.11.0->mcp>=1.0.0->memctrl) (0.7.0)
Requirement already satisfied: pydantic-core==2.46.4 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from pydantic<3.0.0,>=2.11.0->mcp>=1.0.0->memctrl) (2.46.4)
Requirement already satisfied: attrs>=22.2.0 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from jsonschema>=4.20.0->mcp>=1.0.0->memctrl) (26.1.0)
Requirement already satisfied: jsonschema-specifications>=2023.03.6 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from jsonschema>=4.20.0->mcp>=1.0.0->memctrl) (2025.9.1)
Requirement already satisfied: referencing>=0.28.4 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from jsonschema>=4.20.0->mcp>=1.0.0->memctrl) (0.37.0)
Requirement already satisfied: rpds-py>=0.25.0 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from jsonschema>=4.20.0->mcp>=1.0.0->memctrl) (0.30.0)
Requirement already satisfied: cryptography>=3.4.0 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from pyjwt[crypto]>=2.10.1->mcp>=1.0.0->memctrl) (48.0.0)
Requirement already satisfied: cffi>=2.0.0 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from cryptography>=3.4.0->pyjwt[crypto]>=2.10.1->mcp>=1.0.0->memctrl) (2.0.0)
Requirement already satisfied: pycparser in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from cffi>=2.0.0->cryptography>=3.4.0->pyjwt[crypto]>=2.10.1->mcp>=1.0.0->memctrl) (3.0)
Requirement already satisfied: markdown-it-py>=2.2.0 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from rich>=13.0.0->memctrl) (4.0.0)
Requirement already satisfied: pygments<3.0.0,>=2.13.0 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from rich>=13.0.0->memctrl) (2.20.0)
Requirement already satisfied: mdurl~=0.1 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from markdown-it-py>=2.2.0->rich>=13.0.0->memctrl) (0.1.2)
Requirement already satisfied: click>=8.2.1 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from typer>=0.12.0->memctrl) (8.3.3)
Requirement already satisfied: shellingham>=1.3.0 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from typer>=0.12.0->memctrl) (1.5.4)
Requirement already satisfied: annotated-doc>=0.0.2 in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from typer>=0.12.0->memctrl) (0.0.4)
Requirement already satisfied: colorama in C:\Users\kjsc\AppData\Local\Programs\Python\Python313\Lib\site-packages (from click>=8.2.1->typer>=0.12.0->memctrl) (0.4.6)
Downloading memctrl-1.0.1-py3-none-any.whl (35 kB)
Installing collected packages: memctrl
Attempting uninstall: memctrl
Found existing installation: memctrl 1.0.0
Uninstalling memctrl-1.0.0:
Successfully uninstalled memctrl-1.0.0
Successfully installed memctrl-1.0.1

MemCtrl v1.0.1

chore: bump version to 1.0.1

Prepare for Trusted Publishing test via GitHub Releases.
Version 1.0.0 already exists on PyPI and cannot be overwritten.

MemCtrl v1.0.0 — Cognitive Memory Runtime for AI Agents

MemCtrl v1.0.0 — Cognitive Memory Runtime for AI Agents

Overview

MemCtrl is an operating system for long-lived agent memory — hierarchical, explainable, and self-managing. It replaces passive vector dumps with human-like memory layers that remember, forget, consolidate, and explain their reasoning.

What's Included

Core Architecture

• Hierarchical memory layers — Project (forever), Session (7 days), User (90 days)
• Tree-based retrieval — LLM reasons over memory structure, not vector similarity
• Reasoning traces — Every answer shows its exact path: root -> project -> auth -> jwt
• Automatic consolidation — Session memories merge into project knowledge via trigger rules
• Security-first — Secrets, API keys, and PII are redacted before storage

Integrations

• LangGraph — MemCtrlSaver checkpoint saver + MemoryNode for agent workflows
• MCP — Stdio transport server for IDE integration
• Claude Code / Cursor / Kimi Code / Codex — SKILL.md registration via memctrl install

CLI Commands

• memctrl init — Create .memoryrc
• memctrl add — Store memory with layer, tags, confidence
• memctrl query — Retrieve with reasoning trace
• memctrl heatmap — Visualize memory distribution
• memctrl timeline — Chronological memory events
• memctrl tree — Hierarchical tree view
• memctrl trigger-cmd — Fire automation rules
• memctrl audit — Complete trigger log

Demos & Benchmarks

• examples/coding_agent_demo.py — Multi-session agent simulation
• examples/killer_demo.py — Bug prevention across sprints (the "holy sh*t" moment)
• examples/langgraph_integration.py — LangGraph usage patterns
• benchmarks/retention_benchmark.py — Measurable retention vs naive baseline

Visualizer

• Interactive memory graph: Live Demo
• Landing page: https://kj-aiml.github.io/memctrl/

Installation

pip install memctrl

Quick Start

memctrl init
memctrl add "we use FastAPI + PostgreSQL" --layer project
memctrl query "what is our stack?"
# Trace: root -> project -> tech_stack -> FastAPI + PostgreSQL

Benchmarks

Metric	Vector RAG	MemCtrl
Context Retention (10-turn)	62%	91%
Retrieval Explainability	0%	100%
Memory Management Overhead	Manual	Zero ops
Long-Horizon Task Success	45%	78%

Links

• Repository: https://github.com/KJ-AIML/memctrl
• Landing Page: https://kj-aiml.github.io/memctrl/
• Memory Visualizer: https://kj-aiml.github.io/memctrl/memory-viz.html
• Documentation: See README.md
• Technical Article: ARTICLE.md

Thanks

To everyone who shaped MemCtrl's direction. This is just the beginning.

---

Full Changelog: https://github.com/KJ-AIML/memctrl/commits/v1.0.0