memctrl 1.0.0__tar.gz → 1.0.1__tar.gz

memctrl-1.0.1/DISTRIBUTION.md

@@ -0,0 +1,309 @@
+# MemCtrl Distribution Playbook
+
+> Ready-to-use launch materials. Copy, tweak, post.
+
+---
+
+## 1. X/Twitter Thread
+
+```
+Why vector databases are not enough for autonomous agents 🧵
+
+1/ Most agent memory today is "RAG in a trench coat."
+
+Chunk text → embed → dump into vector DB → pray retrieval works.
+
+That fails for agents that need to:
+• Remember decisions forever
+• Forget yesterday's debug session
+• Show HOW they found an answer
+• Learn from mistakes
+
+2/ Human memory is not cosine similarity.
+
+It's layers:
+• Working memory (seconds)
+• Episodic memory (months)
+• Semantic memory (lifetime)
+
+And crucially: consolidation.
+
+Experiences get compressed into knowledge.
+
+3/ Vector DBs don't consolidate.
+
+They don't forget.
+They don't explain.
+They don't evolve.
+
+An agent with vector RAG starts every session from scratch.
+It never gets smarter. It just gets more documents.
+
+4/ So I built MemCtrl — a cognitive memory runtime for AI agents.
+
+Instead of dumping text into vectors, MemCtrl uses:
+• Hierarchical memory layers (project/session/user)
+• Automatic consolidation (session → project)
+• Tree-based retrieval with reasoning traces
+• Security-first (secrets redacted before storage)
+
+5/ Every retrieval shows its path:
+
+Query: "what auth method do we use?"
+Trace: root → project → auth → jwt_refresh_bug
+
+You don't just get an answer.
+You get the reasoning path.
+
+6/ The "holy sh*t" moment:
+
+Sprint 1: Agent hits JWT bug, fixes it, stores in memory.
+Sprint 3: Same bug almost happens again.
+Agent queries memory → remembers incident → prevents regression.
+
+This is not RAG. This is cognition.
+
+7/ MemCtrl integrates with:
+• LangGraph (checkpoint saver + memory node)
+• Claude Code / Cursor / Kimi Code
+• MCP servers
+
+pip install memctrl
+memctrl init
+memctrl add "we use FastAPI + PostgreSQL"
+
+8/ We built benchmarks comparing MemCtrl vs naive vector RAG:
+
+• Context retention: +47%
+• Explainability: 0% → 100%
+• Memory management: manual → zero ops
+
+All local. No cloud. Your data never leaves your machine.
+
+9/ Interactive memory visualizer:
+
+Live demo → https://kj-aiml.github.io/memctrl/memory-viz.html
+
+See your agent's memory as a graph.
+Watch retrieval traces in real time.
+
+10/ MemCtrl is open source under MIT.
+
+We're not building a wrapper.
+We're building the memory operating system for AI agents.
+
+→ https://github.com/KJ-AIML/memctrl
+
+Star + try it. Let me know what you think.
+```
+
+---
+
+## 2. Hacker News Post
+
+**Title:** Show HN: MemCtrl — Cognitive memory runtime for AI agents
+
+**Body:**
+```
+Most agent memory today is RAG in a trench coat: chunk, embed, dump into vector DB, pray.
+
+That works for simple Q&A. It fails for agents that need to remember architectural decisions forever, forget yesterday's debugging session automatically, and explain exactly how they found an answer.
+
+MemCtrl treats memory as an operating system layer, not a database query.
+
+What it does differently:
+
+• Hierarchical memory layers (project/session/user) with different lifespans
+• Automatic consolidation — session notes get distilled into permanent project knowledge
+• Tree-based retrieval with reasoning traces — every answer shows its path
+• Security-first — secrets and PII are redacted before storage
+• Local-only by default — SQLite, no cloud, no telemetry
+
+Benchmarks vs naive vector RAG:
+
+• Context retention (10-turn): 62% → 91%
+• Retrieval explainability: 0% → 100%
+• Memory management overhead: manual → zero ops
+
+Integrations: LangGraph (checkpoint saver + memory node), Claude Code, Cursor, Kimi Code, MCP.
+
+Live visualizer: https://kj-aiml.github.io/memctrl/memory-viz.html
+
+Repo: https://github.com/KJ-AIML/memctrl
+
+Would love feedback from anyone building long-running agents.
+```
+
+---
+
+## 3. Reddit Post
+
+**Title:** I got tired of agents forgetting everything — so I built a cognitive memory runtime
+
+**Body:**
+```
+Every AI agent builder knows the pain:
+
+You spend hours architecting a system, the agent works great for one session, then next session it's like nothing happened. All context lost. Same bugs repeated. Same questions asked.
+
+Vector RAG doesn't solve this. It retrieves similar text. It doesn't *remember*.
+
+So I built MemCtrl — a memory operating system for AI agents.
+
+Instead of embedding chunks, MemCtrl uses human-like memory layers:
+
+• Project memory — permanent (tech stack, ADRs, architectural decisions)
+• Session memory — ephemeral 7 days (daily WIP, debugging)
+• User memory — 90 days (preferences, working style)
+
+And automatic consolidation: session notes get distilled into project knowledge at the end of each sprint.
+
+Every retrieval includes a reasoning trace. You can see exactly how the agent found its answer:
+
+root → project → auth → jwt_refresh_bug → "validate refresh BEFORE access expiry"
+
+The killer demo: an agent that prevents the same production bug from happening twice because it actually remembers the incident 6 weeks later.
+
+Tech stack: Python 3.10+, SQLite, optional LLM backends (OpenAI, LiteLLM, Ollama).
+
+Integrates with LangGraph, Claude Code, Cursor, MCP.
+
+Try it:
+pip install memctrl
+memctrl init
+memctrl add "your first memory"
+
+Repo + visualizer: https://github.com/KJ-AIML/memctrl
+
+Would love to hear from others building persistent agent memory. What's your approach?
+```
+
+**Subreddits:**
+- r/LocalLLaMA
+- r/LangChain
+- r/MachineLearning
+- r/singularity
+
+---
+
+## 4. Release Notes (for GitHub Release)
+
+```markdown
+## MemCtrl v1.0.0 — Cognitive Memory Runtime for AI Agents
+
+### What's New
+
+- **Hierarchical memory layers** — project (forever), session (7 days), user (90 days)
+- **Tree-based retrieval** — LLM reasons over memory structure, not vectors
+- **Reasoning traces** — every answer shows its exact path
+- **Automatic consolidation** — session memories merge into project knowledge
+- **Security-first** — secrets/PII redacted before storage
+- **LangGraph integration** — MemCtrlSaver checkpoint + MemoryNode
+- **MCP server** — stdio transport for IDE integration
+- **Interactive visualizer** — memory graph, timeline, trace viewer
+- **CLI tools** — heatmap, timeline, audit, tree view
+- **Benchmarks** — measurable retention, precision, trace accuracy
+
+### Installation
+
+```bash
+pip install memctrl
+```
+
+### Quick Start
+
+```bash
+memctrl init
+memctrl add "we use FastAPI + PostgreSQL"
+memctrl query "what is our stack?"
+```
+
+### Resources
+
+- Landing page: https://kj-aiml.github.io/memctrl/
+- Memory visualizer: https://kj-aiml.github.io/memctrl/memory-viz.html
+- Full docs: https://github.com/KJ-AIML/memctrl#readme
+
+### Thanks
+
+To everyone who provided feedback and helped shape MemCtrl's direction.
+```
+
+---
+
+## 5. Email / Newsletter Pitch
+
+**Subject:** The missing piece in agent architecture
+
+**Body:**
+```
+Hi [name],
+
+Quick question: how does your AI agent remember things across sessions?
+
+If the answer is "vector database," you're not alone. But you're also not solving the real problem.
+
+Vector DBs retrieve similar text. They don't:
+• Forget automatically
+• Consolidate experience into knowledge
+• Explain how they found an answer
+• Prevent repeated mistakes
+
+I built MemCtrl to fix this.
+
+It's a cognitive memory runtime for AI agents — hierarchical, explainable, and self-managing.
+
+The one-line pitch: MemCtrl gives agents human-like memory layers with automatic consolidation and full reasoning traces.
+
+Live demo: https://kj-aiml.github.io/memctrl/memory-viz.html
+Repo: https://github.com/KJ-AIML/memctrl
+
+Would love your thoughts.
+
+Best,
+[Your name]
+```
+
+---
+
+## 6. One-Line Pitches
+
+**For Twitter bio:**
+> MemCtrl — Cognitive memory runtime for AI agents. Not RAG. Cognition.
+
+**For GitHub description:**
+> An operating system for long-lived agent memory — hierarchical, explainable, and self-managing.
+
+**For elevator pitch:**
+> MemCtrl replaces vector databases with a human-like memory system for AI agents. Agents remember, forget, consolidate, and explain their reasoning.
+
+**For technical audience:**
+> MemCtrl implements hierarchical memory layers with automatic consolidation and tree-based retrieval traces for autonomous agents.
+
+---
+
+## Launch Sequence
+
+```
+Day 0: PyPI publish + GitHub release
+Day 0: Post X thread
+Day 0: Post Reddit threads
+Day 1: Post Hacker News (Tuesday 8am PST is optimal)
+Day 2: Follow up on comments/questions
+Day 3: Post visualizer clip/GIF on X
+Day 7: Publish technical article on Medium/Dev.to
+Week 2: LangGraph integration tutorial
+Week 3: Community examples + case studies
+```
+
+---
+
+## Assets Needed
+
+- [ ] GitHub release created
+- [ ] PyPI package published
+- [ ] X thread posted
+- [ ] HN post submitted
+- [ ] Reddit posts submitted
+- [ ] Visualizer GIF/clip created
+- [ ] Signature screenshot captured

{memctrl-1.0.0 → memctrl-1.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memctrl
-Version: 1.0.0
+Version: 1.0.1
 Summary: Cognitive Memory Runtime for AI Agents — hierarchical, explainable, and self-managing
 Author: MemCtrl Contributors
 License: MIT
@@ -23,22 +23,32 @@ Requires-Dist: litellm>=1.0.0; extra == 'llm'
 Requires-Dist: openai>=1.0.0; extra == 'llm'
 Description-Content-Type: text/markdown
 
-# MemCtrl
+<p align="center">
+  <img src="docs/memctrl_logo.png" alt="MemCtrl Logo" width="180">
+</p>
 
-> **Cognitive Memory Runtime for AI Agents**
->
-> An operating system for long-lived agent memory — hierarchical, explainable, and self-managing.
+<h1 align="center">MemCtrl</h1>
+
+<p align="center">
+  <strong>Cognitive Memory Runtime for AI Agents</strong><br>
+  An operating system for long-lived agent memory — hierarchical, explainable, and self-managing.
+</p>
 
 [![CI](https://github.com/KJ-AIML/memctrl/actions/workflows/ci.yml/badge.svg)](https://github.com/KJ-AIML/memctrl/actions/workflows/ci.yml)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![PyPI](https://img.shields.io/badge/pypi-memctrl-blue.svg)](https://pypi.org/project/memctrl/)
+[![PyPI](https://img.shields.io/pypi/v/memctrl.svg)](https://pypi.org/project/memctrl/)
 [![Tests](https://img.shields.io/badge/tests-187%2F187%20passing-brightgreen)]()
 
 MemCtrl replaces passive vector dumps with an **active memory hierarchy** inspired by human cognition. Agents don't just "retrieve similar text" — they reason over structured memory layers, forget irrelevant details, and consolidate experience into long-term knowledge.
 
 ```bash
+# Via pip
 pip install memctrl
+
+# Or via uv (fast, no global install needed)
+uvx memctrl
+
 memctrl init
 memctrl add "we use FastAPI + PostgreSQL + Redis cache"
 memctrl query "what is our stack?"
@@ -107,7 +117,14 @@ Rules in `.memoryrc` automatically move, summarize, or expire memories between l
 ## 🚀 One-Command Quick Start
 
 ```bash
+# Option 1: pip
 pip install memctrl
+
+# Option 2: uv — fast, modern Python packaging
+uvx memctrl           # run without installing
+# or
+uv tool install memctrl  # install permanently
+
 memctrl init          # creates .memoryrc in your project
 memctrl install       # registers SKILL.md with your AI assistant
 ```
@@ -325,10 +342,22 @@ This demo simulates an AI coding agent working across multiple sessions. Watch h
 
 ## 📦 Requirements
 
-| Requirement | Minimum |
-|---|---|
-| Python | 3.10+ |
-| SQLite | bundled with Python |
+| Requirement | Minimum | Recommended |
+|---|---|---|
+| Python | 3.10+ | 3.12+ |
+| SQLite | bundled with Python | — |
+| Package manager | pip | [uv](https://github.com/astral-sh/uv) |
+
+**Install via pip:**
+```bash
+pip install memctrl
+```
+
+**Install via uv (faster, no global clutter):**
+```bash
+uvx memctrl              # run once, no install
+uv tool install memctrl  # install as a tool
+```
 
 Optional LLM backends (for extraction only):
 

memctrl-1.0.1/PYPI_PUBLISH.md

@@ -0,0 +1,106 @@
+# PyPI Publish Guide — MemCtrl
+
+> This package is ready for PyPI. Follow these steps to publish.
+
+---
+
+## Prerequisites
+
+- PyPI account: https://pypi.org/account/register/
+- GitHub repo: https://github.com/KJ-AIML/memctrl
+
+---
+
+## Step 1: Verify the Build
+
+```bash
+python -m build
+```
+
+You should see:
+```
+Successfully built memctrl-1.0.0.tar.gz and memctrl-1.0.0-py3-none-any.whl
+```
+
+✅ Already verified — builds cleanly.
+
+---
+
+## Step 2: Configure Trusted Publishing on PyPI
+
+Trusted Publishing uses OpenID Connect (OIDC) — no API tokens needed.
+
+1. Go to https://pypi.org/manage/account/publishing/
+2. Click **"Add a new pending publisher"**
+3. Fill in:
+   - **PyPI Project Name**: `memctrl`
+   - **Owner**: `KJ-AIML`
+   - **Repository name**: `memctrl`
+   - **Workflow name**: `publish.yml`
+   - **Environment name**: `pypi`
+4. Click **"Add"**
+
+---
+
+## Step 3: Publish via GitHub Release
+
+1. Go to https://github.com/KJ-AIML/memctrl/releases
+2. Click **"Draft a new release"**
+3. Choose tag: `v1.0.0` (create new tag)
+4. Release title: `MemCtrl v1.0.0 — Cognitive Memory Runtime`
+5. Description: copy from `DISTRIBUTION.md` → Release Notes section
+6. Click **"Publish release"**
+
+The GitHub Action `.github/workflows/publish.yml` will auto-trigger and publish to PyPI.
+
+---
+
+## Step 4: Verify
+
+Wait 2-3 minutes, then check:
+
+```bash
+pip install memctrl
+memctrl --version
+```
+
+Should output: `MemCtrl v1.0.0`
+
+---
+
+## Step 5: Update README Badge
+
+After publish, the PyPI badge in README will auto-update:
+
+```markdown
+[![PyPI](https://img.shields.io/pypi/v/memctrl.svg)](https://pypi.org/project/memctrl/)
+```
+
+Replace the current placeholder badge with this dynamic one.
+
+---
+
+## Troubleshooting
+
+### "Trusted publisher verification failed"
+- Double-check the workflow name is exactly `publish.yml`
+- Ensure the environment name in PyPI matches `pypi` (in the workflow)
+
+### "Project name already taken"
+- Check if `memctrl` exists: https://pypi.org/project/memctrl/
+- If taken, consider `memctrl-ai` or `agent-memory`
+- Update `pyproject.toml` name field
+
+### Build fails
+- Ensure `hatchling` is installed: `pip install hatchling`
+- Ensure version in `memctrl/__init__.py` matches `pyproject.toml`
+
+---
+
+## Post-Publish Checklist
+
+- [ ] `pip install memctrl` works on clean machine
+- [ ] `memctrl --version` shows correct version
+- [ ] PyPI page renders README correctly
+- [ ] Badges update on GitHub
+- [ ] Announce on X/Twitter, HN, Reddit

{memctrl-1.0.0 → memctrl-1.0.1}/README.md

@@ -1,19 +1,29 @@
-# MemCtrl
+<p align="center">
+  <img src="docs/memctrl_logo.png" alt="MemCtrl Logo" width="180">
+</p>
 
-> **Cognitive Memory Runtime for AI Agents**
->
-> An operating system for long-lived agent memory — hierarchical, explainable, and self-managing.
+<h1 align="center">MemCtrl</h1>
+
+<p align="center">
+  <strong>Cognitive Memory Runtime for AI Agents</strong><br>
+  An operating system for long-lived agent memory — hierarchical, explainable, and self-managing.
+</p>
 
 [![CI](https://github.com/KJ-AIML/memctrl/actions/workflows/ci.yml/badge.svg)](https://github.com/KJ-AIML/memctrl/actions/workflows/ci.yml)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![PyPI](https://img.shields.io/badge/pypi-memctrl-blue.svg)](https://pypi.org/project/memctrl/)
+[![PyPI](https://img.shields.io/pypi/v/memctrl.svg)](https://pypi.org/project/memctrl/)
 [![Tests](https://img.shields.io/badge/tests-187%2F187%20passing-brightgreen)]()
 
 MemCtrl replaces passive vector dumps with an **active memory hierarchy** inspired by human cognition. Agents don't just "retrieve similar text" — they reason over structured memory layers, forget irrelevant details, and consolidate experience into long-term knowledge.
 
 ```bash
+# Via pip
 pip install memctrl
+
+# Or via uv (fast, no global install needed)
+uvx memctrl
+
 memctrl init
 memctrl add "we use FastAPI + PostgreSQL + Redis cache"
 memctrl query "what is our stack?"
@@ -82,7 +92,14 @@ Rules in `.memoryrc` automatically move, summarize, or expire memories between l
 ## 🚀 One-Command Quick Start
 
 ```bash
+# Option 1: pip
 pip install memctrl
+
+# Option 2: uv — fast, modern Python packaging
+uvx memctrl           # run without installing
+# or
+uv tool install memctrl  # install permanently
+
 memctrl init          # creates .memoryrc in your project
 memctrl install       # registers SKILL.md with your AI assistant
 ```
@@ -300,10 +317,22 @@ This demo simulates an AI coding agent working across multiple sessions. Watch h
 
 ## 📦 Requirements
 
-| Requirement | Minimum |
-|---|---|
-| Python | 3.10+ |
-| SQLite | bundled with Python |
+| Requirement | Minimum | Recommended |
+|---|---|---|
+| Python | 3.10+ | 3.12+ |
+| SQLite | bundled with Python | — |
+| Package manager | pip | [uv](https://github.com/astral-sh/uv) |
+
+**Install via pip:**
+```bash
+pip install memctrl
+```
+
+**Install via uv (faster, no global clutter):**
+```bash
+uvx memctrl              # run once, no install
+uv tool install memctrl  # install as a tool
+```
 
 Optional LLM backends (for extraction only):
 

memctrl-1.0.1/RELEASE_NOTES.md

@@ -0,0 +1,79 @@
+## 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](https://kj-aiml.github.io/memctrl/memory-viz.html)
+- Landing page: [https://kj-aiml.github.io/memctrl/](https://kj-aiml.github.io/memctrl/)
+
+### Installation
+
+```bash
+pip install memctrl
+```
+
+### Quick Start
+
+```bash
+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](https://github.com/KJ-AIML/memctrl#readme)
+- **Technical Article**: [ARTICLE.md](https://github.com/KJ-AIML/memctrl/blob/master/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

{memctrl-1.0.0 → memctrl-1.0.1}/docs/index.html

@@ -380,7 +380,10 @@
 
     <nav>
         <div class="container">
-            <div class="logo">MemCtrl</div>
+            <div style="display: flex; align-items: center; gap: 12px;">
+                <img src="memctrl_logo.png" alt="MemCtrl" style="height: 32px; width: 32px; border-radius: 8px;">
+                <div class="logo">MemCtrl</div>
+            </div>
             <div class="nav-links">
                 <a href="#features">Features</a>
                 <a href="#architecture">Architecture</a>
@@ -398,9 +401,13 @@
             <div class="hero-buttons">
                 <a href="https://github.com/KJ-AIML/memctrl" class="btn btn-primary">Get Started</a>
                 <a href="https://pypi.org/project/memctrl/" class="btn btn-secondary">pip install memctrl</a>
+                <a href="https://docs.astral.sh/uv/" class="btn btn-secondary" style="border-color: var(--accent-secondary); color: var(--accent-secondary);">uvx memctrl</a>
             </div>
 
             <div class="code-block">
+<span class="comment"># Install via pip or uv</span><br>
+<span class="prompt">$</span> pip install memctrl<br>
+<span class="comment"># or: uvx memctrl (no install needed)</span><br><br>
 <span class="prompt">$</span> memctrl init<br>
 <span class="comment"># Created .memoryrc</span><br><br>
 <span class="prompt">$</span> memctrl add <span class="string">"we use FastAPI + PostgreSQL"</span> --layer project<br>