memctrl 1.0.1__tar.gz → 1.1.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memctrl
-Version: 1.0.1
+Version: 1.1.0
 Summary: Cognitive Memory Runtime for AI Agents — hierarchical, explainable, and self-managing
 Author: MemCtrl Contributors
 License: MIT
@@ -150,15 +150,12 @@ Register the skill with your AI assistant:
 
 | Platform | Command |
 |---|---|
-| Claude Code | `memctrl install --platform claude` |
-| Codex | `memctrl install --platform codex` |
-| Cursor | `memctrl install --platform cursor` |
-| Kimi Code | `memctrl install --platform kimi` |
-| Gemini CLI | `memctrl install --platform gemini` |
-| Aider | `memctrl install --platform aider` |
-| VS Code Copilot Chat | `memctrl install --platform vscode` |
-| GitHub Copilot CLI | `memctrl install --platform copilot` |
-| Pi | `memctrl install --platform pi` |
+| Claude Code | `memctrl install --tool claude_code` |
+| Codex | `memctrl install --tool codex` |
+| Cursor | `memctrl install --tool cursor` |
+| Kimi Code | `memctrl install --tool kimi` |
+| Pi | `memctrl install --tool pi` |
+| AxGa | `memctrl install --tool axga` |
 
 Project-scoped install (commits into your repo):
 
@@ -263,7 +260,7 @@ MemCtrl is designed to plug into existing agent stacks:
 | Framework | Status | Notes |
 |---|---|---|
 | **MCP** | ✅ Ready | Stdio transport server included |
-| **Claude Code** | ✅ Ready | `memctrl install --platform claude` |
+| **Claude Code** | ✅ Ready | `memctrl install --tool claude_code` |
 | **LangGraph** | ✅ Ready | `MemCtrlSaver` checkpoint + `MemoryNode` |
 | **CrewAI** | 🚧 Planned | Long-term memory backend |
 | **AutoGen** | 🚧 Planned | Agent memory provider |

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

@@ -125,15 +125,12 @@ Register the skill with your AI assistant:
 
 | Platform | Command |
 |---|---|
-| Claude Code | `memctrl install --platform claude` |
-| Codex | `memctrl install --platform codex` |
-| Cursor | `memctrl install --platform cursor` |
-| Kimi Code | `memctrl install --platform kimi` |
-| Gemini CLI | `memctrl install --platform gemini` |
-| Aider | `memctrl install --platform aider` |
-| VS Code Copilot Chat | `memctrl install --platform vscode` |
-| GitHub Copilot CLI | `memctrl install --platform copilot` |
-| Pi | `memctrl install --platform pi` |
+| Claude Code | `memctrl install --tool claude_code` |
+| Codex | `memctrl install --tool codex` |
+| Cursor | `memctrl install --tool cursor` |
+| Kimi Code | `memctrl install --tool kimi` |
+| Pi | `memctrl install --tool pi` |
+| AxGa | `memctrl install --tool axga` |
 
 Project-scoped install (commits into your repo):
 
@@ -238,7 +235,7 @@ MemCtrl is designed to plug into existing agent stacks:
 | Framework | Status | Notes |
 |---|---|---|
 | **MCP** | ✅ Ready | Stdio transport server included |
-| **Claude Code** | ✅ Ready | `memctrl install --platform claude` |
+| **Claude Code** | ✅ Ready | `memctrl install --tool claude_code` |
 | **LangGraph** | ✅ Ready | `MemCtrlSaver` checkpoint + `MemoryNode` |
 | **CrewAI** | 🚧 Planned | Long-term memory backend |
 | **AutoGen** | 🚧 Planned | Agent memory provider |

{memctrl-1.0.1 → memctrl-1.1.0}/memctrl/__init__.py

@@ -4,7 +4,7 @@ Inspired by PageIndex's tree-based retrieval and Graphify's install pattern.
 Uses hierarchical reasoning (not vectors) for explainable memory retrieval.
 """
 
-__version__ = "1.0.1"
+__version__ = "1.1.0"
 
 from memctrl.store import Memory, MemoryStore, TriggerLog, TreeNode
 from memctrl.retriever import RetrievalResult

{memctrl-1.0.1 → memctrl-1.1.0}/memctrl/cli.py

@@ -37,11 +37,34 @@ console = Console()
 
 
 def _get_store():
-    """Get MemoryStore instance with default DB path."""
+    """Get MemoryStore instance with project-local or global DB path."""
     from memctrl.store import MemoryStore
 
+    # 1. Environment variable overrides everything
     db_path = os.environ.get("MEMCTRL_DB_PATH")
-    return MemoryStore(db_path)
+    if db_path:
+        return MemoryStore(db_path)
+
+    # 2. If .memoryrc exists in cwd, use its db_path
+    rc_path = Path(".memoryrc")
+    if rc_path.exists():
+        try:
+            from memctrl.rules import RuleEngine
+
+            engine = RuleEngine(str(rc_path))
+            rules = engine.load()
+            if rules.db_path:
+                # Resolve relative to .memoryrc location (cwd)
+                resolved = Path(rules.db_path)
+                if not resolved.is_absolute():
+                    resolved = rc_path.parent / resolved
+                resolved.parent.mkdir(parents=True, exist_ok=True)
+                return MemoryStore(str(resolved))
+        except Exception:
+            pass  # Fallback to global default
+
+    # 3. Global default
+    return MemoryStore()
 
 
 def _get_engine():
@@ -92,7 +115,7 @@ def install(
 def init(
     force: bool = typer.Option(False, help="Overwrite existing .memoryrc"),
 ):
-    """Create .memoryrc in current directory"""
+    """Create .memoryrc and project-local database in current directory"""
     dest = Path(".memoryrc")
     if dest.exists() and not force:
         console.print(
@@ -109,6 +132,18 @@ def init(
     dest.write_text(content)
     console.print(f"[green]Created {dest}[/green]")
 
+    # Create project-local database directory and initialize empty DB
+    db_dir = Path(".memctrl")
+    db_dir.mkdir(parents=True, exist_ok=True)
+    db_path = db_dir / "memories.db"
+    if not db_path.exists():
+        from memctrl.store import MemoryStore
+
+        MemoryStore(str(db_path))  # initializes schema
+        console.print(f"[green]Created {db_path}[/green]")
+    else:
+        console.print(f"[dim]{db_path} already exists[/dim]")
+
 
 @app.command()
 def add(
@@ -464,6 +499,9 @@ def serve(
 def _default_memoryrc() -> str:
     return """# MemCtrl configuration
 
+[memctrl]
+db_path = ".memctrl/memories.db"
+
 [layers]
 project = "architecture decisions, tech stack, ADRs, why we chose X"
 session = "current task, WIP, what was done this session"

{memctrl-1.0.1 → memctrl-1.1.0}/memctrl/installer.py

@@ -38,6 +38,10 @@ TOOL_PATHS = {
     "pi": [
         "~/.pi/agent/skills/memctrl/SKILL.md",
     ],
+    "kimi": [
+        "~/.kimi/skills/memctrl/SKILL.md",
+        ".kimi/skills/memctrl/SKILL.md",
+    ],
 }
 
 
@@ -66,7 +70,7 @@ def install_skill(
     """Install SKILL.md for specified tool or all detected tools.
 
     Args:
-        tool: Specific tool name (claude_code, cursor, codex, etc.)
+        tool: Specific tool name (claude_code, cursor, codex, kimi, etc.)
         project: If True, install to project-level paths (e.g., .claude/)
         verbose: Print summary
 
@@ -118,6 +122,6 @@ def install_skill(
                 for p in paths:
                     print(f"  {tool_name}: {p}")
             print("\nTo force install for a specific tool, use:")
-            print("  memctrl install --tool claude_code")
+            print("  memctrl install --tool kimi")
 
     return installed_paths

{memctrl-1.0.1 → memctrl-1.1.0}/memctrl/rules.py

@@ -43,6 +43,7 @@ class Rules:
     forget_never: List[str] = field(default_factory=list)
     forget_after_days: Dict[str, int] = field(default_factory=dict)
     confidence: Dict[str, float] = field(default_factory=dict)
+    db_path: Optional[str] = None
 
     def get_ttl_days(self, layer: str) -> Optional[int]:
         return self.forget_after_days.get(layer)
@@ -151,6 +152,12 @@ class RuleEngine:
                     k: float(v) for k, v in extract["confidence"].items()
                 }
 
+        # [memctrl]
+        if "memctrl" in data:
+            memctrl_cfg = data["memctrl"]
+            if "db_path" in memctrl_cfg:
+                rules.db_path = str(memctrl_cfg["db_path"])
+
         self.rules = rules
         return rules
 

memctrl-1.1.0/memctrl/templates/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: memctrl
+description: |
+  MANDATORY: Before starting ANY work in this project, load context from
+  memctrl. After finishing work, store what was learned. This is the project's
+  cognitive memory layer — not optional.
+  
+  CRITICAL RULES:
+  1. ALWAYS run `memctrl query "current project context"` at session start
+  2. ALWAYS run `memctrl add` after architecture decisions or discoveries
+  3. ALWAYS run `memctrl trigger on_session_end` before ending session
+  4. NEVER say "I don't remember" — query memctrl first
+---
+
+# MemCtrl — Mandatory Memory Protocol
+
+## ⚡ Session Start Protocol (REQUIRED)
+
+Run this **before** any coding, planning, or discussion:
+
+```bash
+memctrl query "current project context"
+memctrl query "what decisions have been made"
+memctrl query "what is the tech stack"
+```
+
+If no context exists (new project), initialize:
+```bash
+memctrl init --force
+```
+
+## 📝 During Work — Store Automatically
+
+After ANY of these events, run `memctrl add` **immediately**:
+
+| Event | Example Command |
+|-------|----------------|
+| Architecture decision | `memctrl add "Using FastAPI + async SQLAlchemy" --layer project` |
+| Bug discovered | `memctrl add "JWT validation fails on expired tokens — use jose` --layer project` |
+| Tech choice | `memctrl add "Chose PostgreSQL over SQLite for concurrent writes" --layer project` |
+| Current task | `memctrl add "Implementing OAuth2 login flow" --layer session` |
+| User preference | `memctrl add "Prefers explicit types over generics" --layer user` |
+| Refactoring | `memctrl add "Renamed UserService -> AuthService" --layer project` |
+
+## 🏁 Session End Protocol (REQUIRED)
+
+Before ending ANY session:
+
+```bash
+memctrl trigger on_session_end
+memctrl audit
+```
+
+This consolidates session memories and cleans up expired entries.
+
+## 🔍 When User Asks Context Questions
+
+If user asks anything like:
+- "Why did we choose X?"
+- "What was the decision about Y?"
+- "What were we doing last time?"
+- "What's our tech stack?"
+
+**NEVER guess.** Always run:
+```bash
+memctrl query "<user's question>"
+```
+
+## 🧠 Memory Layers
+
+| Layer | Purpose | When to Use | Expiry |
+|-------|---------|-------------|--------|
+| **project** | Architecture, ADRs, tech stack, refactors | Permanent decisions | Never |
+| **session** | Current task, WIP, what was done today | Temporary work | 7 days |
+| **user** | Preferences, coding style, patterns | Personal habits | 90 days |
+
+## 📋 Quick Commands
+
+```bash
+memctrl query "<question>"              # Retrieve with reasoning trace
+memctrl add "<fact>" --layer project    # Store permanent knowledge
+memctrl add "<fact>" --layer session    # Store temporary work
+memctrl tree                             # View full memory hierarchy
+memctrl trigger on_session_end          # Consolidate & cleanup
+memctrl audit                            # Review memory log
+```
+
+## 🌐 MCP Server (if running)
+
+If `memctrl serve` is active, use these tools directly:
+- `memctrl_query(query, layer?)` — Retrieve memories
+- `memctrl_add(content, layer, source?)` — Store memory
+- `memctrl_trigger(event, context?)` — Fire rule trigger
+- `memctrl_tree()` — Get memory hierarchy
+- `memctrl_audit(limit?)` — View audit log

{memctrl-1.0.1 → memctrl-1.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "memctrl"
-version = "1.0.1"
+version = "1.1.0"
 description = "Cognitive Memory Runtime for AI Agents — hierarchical, explainable, and self-managing"
 readme = "README.md"
 license = {text = "MIT"}

memctrl-1.0.1/memctrl/templates/SKILL.md

@@ -1,63 +0,0 @@
----
-name: memctrl
-description: >
-  Rule-governed memory layer for this project. Call memctrl to store,
-  retrieve, or update memory about this project, session, or user preferences.
-  Use this when:
-  - Starting a new session (load context)
-  - Making an architecture decision (store to project layer)
-  - Finishing work (trigger on_session_end)
-  - Asking "what did we decide about X" (query memory tree)
----
-
-# MemCtrl Memory System
-
-## When to Use
-
-- **Session start**: Run `memctrl query "current project context"` for instant context
-- **Architecture decisions**: Run `memctrl add --layer project "decided to use X because Y"`
-- **Session end**: Run `memctrl trigger on_session_end` to consolidate memories
-- **Any context question**: Run `memctrl query "<your question>"`
-
-## Memory Layers
-
-| Layer | Purpose | Default Expiry |
-|-------|---------|---------------|
-| project | Architecture decisions, tech stack, ADRs | Never |
-| session | Current task, WIP, what was done this session | 7 days |
-| user | Personal preferences, working style, patterns | 90 days |
-
-## Key Commands
-
-```bash
-# Query what you need
-memctrl query "what is our tech stack?"
-memctrl query "why did we choose PostgreSQL?"
-
-# Store decisions
-memctrl add "decided to use Firecracker for sandbox isolation" --layer project
-memctrl add "currently implementing auth flow" --layer session
-memctrl add "prefers async Python, minimal abstractions" --layer user
-
-# Manage
-memctrl tree                    # view full memory tree
-memctrl trigger on_session_end  # consolidate session memories
-memctrl audit                   # review what was remembered/forgotten
-```
-
-## How Retrieval Works
-
-MemCtrl uses tree-based reasoning (like PageIndex) instead of vector similarity:
-- Memories are organized in a semantic tree: project/tech_stack/database
-- When you query, the system reasons about which branches to explore
-- Results include a trace: root → project → tech_stack → database
-- No embeddings needed — pure structured reasoning
-
-## MCP Server
-
-If the MCP server is running (`memctrl serve`), these tools are available:
-- `memctrl_query(query, layer?)` → Retrieve memories with trace
-- `memctrl_add(content, layer, source?)` → Store a memory
-- `memctrl_trigger(event, context?)` → Fire a trigger
-- `memctrl_tree()` → Get full memory tree
-- `memctrl_audit(limit?)` → View audit log