@muxtsou/memory-cell 0.1.5 → 0.1.7

package/README.md

@@ -19,19 +19,16 @@
 
 ## 🤯 Problems & Dilemmas of Agents
 
-Despite using frontier models, developers and engineering teams face painful realities every single day:
+To make autonomous agents truly capable, they need **mind, alignment, and continuity**. Yet in reality, teams scaling agents hit 3 fatal bottlenecks every single day:
 
-1. 💸 **The Amnesia Tax (Paying to Re-explain Everything)**  
-   Every new session erases working context. You are forced to repeatedly paste code snippets, re-explain architecture, and burn thousands of tokens just to bring the AI back up to speed, destroying unit economics.
+1. 💸 **"Burning 90% Tokens on Noise: The Cost & Quota Wall" (The Marginal Waste)**  
+   Without precision memory, agents brute-force entire files and histories on every turn. You either hit humiliating weekly usage caps mid-sprint, or burn thousands of dollars on sluggish 30-second context evaluation that destroys product margins.
 
-2. 🌀 **The "Smart but Blind" Dilemma (Local Fixes, Global Breakages)**  
-   Agents write great code in isolation, but are completely blind to overall codebase topology. They confidently fix function A while silently breaking service B, turning code generation into an endless debugging loop.
+2. 🌀 **"Fixed One Function, Silently Broke Three Other Services" (The Blind-Spot Bug)**  
+   Agents write code with supreme confidence, but they can't see beyond the file in front of them. The AI happily renames a parameter or tweaks logic in module A, completely unaware that services B and C depend on it—turning a 2-minute fix into hours of debugging regressions.
 
-3. 🏰 **The Knowledge Silo & Sovereignty Lock-in (Zero Cross-Tool Neutrality)**  
-   Hard-won fixes and proprietary architectural insights are trapped inside vendor silos. Moving between Cursor, Claude Code, Windsurf, or Terminal means resetting experience to zero. Teams lack a sovereign, platform-neutral memory layer that they truly own.
-
-4. ⚖️ **The Knowledge Governance Void (Unversioned, Stale & Ungoverned Context)**  
-   Technical specs and ADRs evolve continuously, but vector black boxes cannot surgically prune stale rules. Deprecated patterns poison future runs, with zero line-level audit trails back to authoritative sources.
+3. 🏰 **"Millions of Tokens Burned, Zero Knowledge Owned" (The Hostage & Amnesia Trap)**  
+   Hard-won bug fixes, custom architectural invariants, and domain SOPs are held hostage inside closed IDEs and cloud black boxes. Without a sovereign, tool-neutral memory layer, your team's collective intelligence never compounds—it evaporates the moment you switch tools or models, forcing agents to reset to day zero forever.
 
 ---
 
@@ -69,7 +66,7 @@ Despite using frontier models, developers and engineering teams face painful rea
 ## 🚀 Key Benefits
 
 - ⚡ **< 15ms P75 In-Conversation Retrieval**: Instant precision grounding across code, living documentation, and shared team playbooks without context lag.
-- 🗜️ **50%–90% Token Reduction**: Decoupled reasoning retrieves only the necessary context window without stuffing entire files or brute-forcing vector chunks.
+- 🗜️ **50%–90% Token Reduction**: Surgically pinpoints only the relevant lines and sections instead of dumping entire files or flooding context with noisy fragments.
 - 🛡️ **Zero GraphDB Overhead**: Pure embedded SQLite architecture. Zero Neo4j, Redis, or external vector service dependencies.
 - 🌐 **True Cross-Tool Continuity**: Works seamlessly across Claude Code, Cursor, Windsurf, Codex, Gemini, Terminal, and CI/CD pipelines via universal MCP protocols.
 - 🔄 **Zero-Friction Living Knowledge**: Edit any markdown file or code in your repo as usual. Memory Cell automatically hot-syncs changes and prunes deleted files in real-time.
@@ -107,14 +104,12 @@ Run directly inside any project repository root:
 memory-cell init
 ```
 
-✨ **Automatically detects and configures all supported environments on your machine:**
-- [x] **Google Antigravity** (`.agents/mcp_config.json` + `hooks.json` + `skills/` + `plugin.json`)
-- [x] **Cursor IDE** (`.cursor/mcp.json`)
-- [x] **Claude Code CLI** (`.mcp.json` + `.claude/hooks.json` + `.claude/commands/`)
-- [x] **OpenCode Interpreter** (`.opencode/mcp.json`)
-- [x] **Hermes Agent** (`.hermes/config.yaml`)
-- [x] **OpenAI Codex CLI** (`.codex/config.toml`)
-- [x] **GitHub Copilot / VS Code** (`.vscode/mcp.json`)
+✨ **Automatically detects and provisions MCP tools, life-cycle hooks, and agent skills across your development stack:**
+- **Anthropic Claude**: Claude Code CLI, Claude Desktop
+- **Google Antigravity**: Antigravity IDE, Antigravity CLI (`agy`)
+- **AI-Native IDEs**: Cursor, Windsurf
+- **VS Code Ecosystem**: GitHub Copilot, Roo Code, Cline
+- **Agent Harnesses**: Hermes Agent, OpenCode Interpreter, Codex
 
 ---
 
@@ -123,26 +118,28 @@ memory-cell init
 Memory Cell equips coding agents with a structured cognitive layer composed of specialized tools that replace noisy brute-force file scanning with surgical, token-efficient intelligence:
 
 ### 1. 🧠 Grounded Reasoning & Unified Search (Cognitive Retrieval)
-- `reason("<query>", workspace_path: ".")`: **Grounding Engine.** Retrieves AST-indexed document sections, active domain concepts, verified workflows, and architectural rules without reading raw files or blowing context tokens.
+- `reason("<query>", workspace_path: ".")`: **Grounding Engine.** Retrieves structured document sections, active domain concepts, verified workflows, and architectural rules without reading raw files or blowing context tokens.
 - `search("<query>")`: **Holographic Search.** Concurrently queries code symbols (`find_symbol`) and long-term memory (`reason`), synthesizing verified code locations and living docs into a single high-density context.
 - `ingest(file_path: "...")`: Ingests documents (Markdown, Code, PDF) through the zero-leakage cognitive pipeline into memory.
 - `forget(id: "...")`: Removes obsolete engrams and their associated living doc from disk.
 
 ### 2. ⚡ Deep Code Intelligence & Topological Navigation (22 Languages)
-Instant AST-level code navigation across 22 major languages in < 15ms P75 lookup:
+Instant syntax-aware code navigation across 22 major languages in < 15ms P75 lookup:
 - `find_symbol("<name>")`: Pinpoints functions, structs, classes, interfaces, traits, and exact line definitions.
 - `trace_callers("<symbol>", direction: "callers" | "callees")`: Bidirectional call hierarchy tracing across files without manual searching.
 - `find_references("<identifier>")`: Locates exact declarations, reads, and writes for variables and fields.
 - `analyze_impact("<symbol>")`: Evaluates blast radius and affected call sites before refactoring critical interfaces.
 
-### 3. 🔄 Autonomous Learning Across 6 Universal Knowledge Dimensions
-Agents and developers autonomously distill experience and preserve knowledge into long-term memory:
-1. 🛠️ `learn_workflow`: Verified step-by-step procedures (SOPs) for automated replay.
-2. ⚠️ `learn_antipattern`: Inhibitory rules that prevent recurring mistakes and hallucinations.
-3. 👤 `learn_preference`: User/team coding style, architectural constraints, and guidelines.
-4. 🏛️ `learn_decision`: Architectural Decision Records (ADRs) and trade-offs.
-5. 💡 `learn_concept`: Domain models, entities, and project terminology.
-6. ⚡ `learn_heuristic`: Fast-and-frugal rules of thumb and optimization shortcuts.
+### 3. 🔄 Autonomous Continuous Learning (Automated Dream Consolidation)
+Zero manual curation or learning commands required. During live development, the **Hippocampus automatically snapshots** fine-grained events, execution trails, and troubleshooting corrections in real time. **Dream Consolidation (`dream()`)** then distills and solidifies these episodic footprints into long-term structured Neocortex knowledge whenever triggered:
+- **Episodic Snapshots ➔ Semantic Engrams**: Distills raw session logs into permanent structured engrams across 6 Universal Knowledge Dimensions:
+  - 🛠️ **Workflows & SOPs**: Verified step-by-step procedures distilled from successful tasks for automated replay.
+  - ⚠️ **Anti-Patterns & Pitfalls**: Inhibitory guardrails learned from bugs, failed attempts, and user corrections.
+  - 👤 **Developer Preferences**: Coding guidelines, project conventions, and stylistic directives.
+  - 🏛️ **Architectural Decisions (ADRs)**: Key trade-offs and structural rationale recorded in context.
+  - 💡 **Domain Concepts**: Project terminology, mental models, and core entity definitions.
+  - ⚡ **Heuristics**: Fast-and-frugal engineering rules of thumb and performance optimizations.
+- **On-Demand Wrap-up & Graph Hygiene**: Run `/dream` (or `memory-cell dream`) whenever you wrap up a task or session—safely pruning redundant noise, resolving contradictions, and crystallizing lessons into Git-tracked assets.
 
 ### 4. 🤝 Cross-Agent Working Memory Handover & Episodic Recall
 - `takeover()`: Switching between different agents, models, or IDEs? Run `/takeover` (or `memory-cell takeover`). The next agent instantly resumes the active goal, obstacle trails, and execution context (<180 tokens) without losing state.
@@ -156,6 +153,21 @@ Agents and developers autonomously distill experience and preserve knowledge int
 
 ---
 
+## ⚡ Agent Skills & Slash Commands (Zero-Friction UX)
+
+`memory-cell init` automatically provisions specialized agent skills and slash commands across all your IDEs and CLI agents (Google Antigravity, Claude Code, Cursor, Codex). Agents proactively load these workflows or you can invoke them directly:
+
+| Slash Command | Agent Skill | Capability & Description |
+| :--- | :--- | :--- |
+| `/takeover` | `takeover` | **Instant Cross-Tool Handover.** Resumes working memory, active subgoals, and obstacles across IDEs in < 180 tokens without manual briefing. |
+| `/dream` | `dream` | **Consolidation & Graph Hygiene.** Runs two-phase consolidation to distill raw episodic sessions into permanent Neocortex knowledge and resolve contradictions. |
+| `/memorize` | `memorize` | **Explicit Knowledge Persistence.** Quickly captures and classifies critical lessons, SOPs, or rules into `.memory/` across 6 dimensions. |
+| `/impact <symbol>` | `impact` | **Blast Radius Evaluation.** Inspects call hierarchies and calculates risk before refactoring critical functions, structs, or traits. |
+| `/recall <query>` | `recall` | **Episodic Timeline Explorer.** Queries chronological debugging trails and past session decisions with forward-timeline synthesis. |
+| `/stats` | `stats` | **Cognitive Health & ROI Scorecard.** Displays managed engram distribution, duplicate filter ratio, and total context token savings. |
+
+---
+
 ## 🧠 Distillation Engine Configuration (Zero-API-Key with Claude Max)
 
 Memory Cell uses an intelligent distillation engine to synthesize session events into long-term structured knowledge. You don't need a separate paid API key if you have a Claude subscription (Claude Pro / Max) or local tools:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@muxtsou/memory-cell",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Cross-platform CLI and MCP cognitive runtime for AI coding assistants",
   "bin": {
     "memory-cell": "bin/run.js"
@@ -27,10 +27,10 @@
     "access": "public"
   },
   "optionalDependencies": {
-    "@muxtsou/memory-cell-darwin-arm64": "0.1.5",
-    "@muxtsou/memory-cell-darwin-x64": "0.1.5",
-    "@muxtsou/memory-cell-linux-x64": "0.1.5",
-    "@muxtsou/memory-cell-linux-arm64": "0.1.5",
-    "@muxtsou/memory-cell-win32-x64": "0.1.5"
+    "@muxtsou/memory-cell-darwin-arm64": "0.1.7",
+    "@muxtsou/memory-cell-darwin-x64": "0.1.7",
+    "@muxtsou/memory-cell-linux-x64": "0.1.7",
+    "@muxtsou/memory-cell-linux-arm64": "0.1.7",
+    "@muxtsou/memory-cell-win32-x64": "0.1.7"
   }
 }