mango-brain 3.3.2__tar.gz → 3.3.4__tar.gz

{mango_brain-3.3.2 → mango_brain-3.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mango-brain
-Version: 3.3.2
+Version: 3.3.4
 Summary: The learning layer for Claude Code — persistent associative memory + development workflow. Claude Code gets smarter the longer you use it.
 Author-email: Federico Anastasi <federico.anastasi@outlook.com>
 License: MIT
@@ -44,7 +44,7 @@ Dynamic: license-file
 
 <p align="center">
   <a href="https://pypi.org/project/mango-brain/"><img src="https://img.shields.io/pypi/v/mangobrain?style=flat-square&color=7c3aed&label=PyPI" /></a>
-  <img src="https://img.shields.io/badge/v3.3.2-7c3aed?style=flat-square" />
+  <img src="https://img.shields.io/badge/v3.3.4-7c3aed?style=flat-square" />
   <img src="https://img.shields.io/badge/python-3.11+-blue?style=flat-square&logo=python&logoColor=white" />
   <img src="https://img.shields.io/badge/MCP-compatible-8A2BE2?style=flat-square" />
   <img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" />

{mango_brain-3.3.2 → mango_brain-3.3.4}/README.md

@@ -15,7 +15,7 @@
 
 <p align="center">
   <a href="https://pypi.org/project/mango-brain/"><img src="https://img.shields.io/pypi/v/mangobrain?style=flat-square&color=7c3aed&label=PyPI" /></a>
-  <img src="https://img.shields.io/badge/v3.3.2-7c3aed?style=flat-square" />
+  <img src="https://img.shields.io/badge/v3.3.4-7c3aed?style=flat-square" />
   <img src="https://img.shields.io/badge/python-3.11+-blue?style=flat-square&logo=python&logoColor=white" />
   <img src="https://img.shields.io/badge/MCP-compatible-8A2BE2?style=flat-square" />
   <img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" />

{mango_brain-3.3.2 → mango_brain-3.3.4}/mango_brain.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mango-brain
-Version: 3.3.2
+Version: 3.3.4
 Summary: The learning layer for Claude Code — persistent associative memory + development workflow. Claude Code gets smarter the longer you use it.
 Author-email: Federico Anastasi <federico.anastasi@outlook.com>
 License: MIT
@@ -44,7 +44,7 @@ Dynamic: license-file
 
 <p align="center">
   <a href="https://pypi.org/project/mango-brain/"><img src="https://img.shields.io/pypi/v/mangobrain?style=flat-square&color=7c3aed&label=PyPI" /></a>
-  <img src="https://img.shields.io/badge/v3.3.2-7c3aed?style=flat-square" />
+  <img src="https://img.shields.io/badge/v3.3.4-7c3aed?style=flat-square" />
   <img src="https://img.shields.io/badge/python-3.11+-blue?style=flat-square&logo=python&logoColor=white" />
   <img src="https://img.shields.io/badge/MCP-compatible-8A2BE2?style=flat-square" />
   <img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" />

{mango_brain-3.3.2 → mango_brain-3.3.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mango-brain"
-version = "3.3.2"
+version = "3.3.4"
 description = "The learning layer for Claude Code — persistent associative memory + development workflow. Claude Code gets smarter the longer you use it."
 readme = "README.md"
 license = {text = "MIT"}

{mango_brain-3.3.2 → mango_brain-3.3.4}/server/cli.py

@@ -683,10 +683,17 @@ apply_elaboration, reinforce, decay, stats, diagnose, list_memories, sync_codeba
 
 def main() -> None:
     """CLI entry point."""
+    from importlib.metadata import version as pkg_version
+
     parser = argparse.ArgumentParser(
         prog="mangobrain",
         description="MangoBrain — Persistent memory + workflow system for Claude Code",
     )
+    try:
+        ver = pkg_version("mango-brain")
+    except Exception:
+        ver = "dev"
+    parser.add_argument("--version", "-V", action="version", version=f"%(prog)s {ver}")
     sub = parser.add_subparsers(dest="command")
 
     # serve

{mango_brain-3.3.2 → mango_brain-3.3.4}/server/config.py

@@ -164,6 +164,7 @@ QUICK_BUDGET = int(_get("retrieval", "quick_budget", "2000"))
 SESSION_QUICK_BUDGET = int(_get("retrieval", "session_quick_budget", "4000"))
 DEEP_MAX_RESULTS = int(_get("retrieval", "deep_max_results", "20"))
 QUICK_MAX_RESULTS = int(_get("retrieval", "quick_max_results", "6"))
+RECENT_MAX_RESULTS = int(_get("retrieval", "recent_max_results", "20"))
 RELEVANCE_THRESHOLD_RATIO = float(_get("retrieval", "deep_threshold", "0.78"))
 QUICK_RELEVANCE_THRESHOLD_RATIO = float(_get("retrieval", "quick_threshold", "0.85"))
 

{mango_brain-3.3.2 → mango_brain-3.3.4}/server/mcp_tools.py

@@ -103,26 +103,9 @@ def register_tools(
                 recent_count = sum(1 for m in memories if m.id in recent_ids)
                 neighbor_count = len(memories) - recent_count
 
-                result = {
-                    "memories": [
-                        {
-                            "id": m.id,
-                            "content": m.content,
-                            "type": m.type.value if hasattr(m.type, 'value') else m.type,
-                            "project": m.project,
-                            "tags": m.tags,
-                            "relevance": round(scores[i], 4),
-                            "file_path": m.file_path,
-                            "code_signature": m.code_signature,
-                            "is_recent": m.id in recent_ids,
-                        }
-                        for i, m in enumerate(memories)
-                    ],
-                    "total_tokens": total_tokens,
-                    "count": len(memories),
-                    "recent_count": recent_count,
-                    "neighbor_count": neighbor_count,
-                }
+                count = len(memories)
+                recent_count_val = recent_count
+                neighbor_count_val = neighbor_count
             else:
                 if not query:
                     return json.dumps({"error": "query is required for deep/quick mode"})
@@ -130,29 +113,37 @@ def register_tools(
                     query=query, mode=mode, project=project,
                     budget=budget, session_id=session_id,
                 )
-                result = {
-                    "memories": [
-                        {
-                            "id": m.id,
-                            "content": m.content,
-                            "type": m.type.value if hasattr(m.type, 'value') else m.type,
-                            "project": m.project,
-                            "tags": m.tags,
-                            "relevance": round(scores[i], 4),
-                            "file_path": m.file_path,
-                            "code_signature": m.code_signature,
-                        }
-                        for i, m in enumerate(memories)
-                    ],
-                    "total_tokens": total_tokens,
-                    "count": len(memories),
-                }
+                count = len(memories)
+                recent_count_val = None
+                neighbor_count_val = None
+
+            # Format as readable text (not raw JSON)
             _dur = int((_time.monotonic_ns() - _t0) / 1_000_000)
             await _log_op(db, "remember", project=project,
                           params={"query": query, "mode": mode, "limit": limit},
-                          result={"count": result["count"], "total_tokens": result["total_tokens"]},
+                          result={"count": count, "total_tokens": total_tokens},
                           duration_ms=_dur)
-            return json.dumps(result, indent=2)
+
+            lines = []
+            header = f"{count} memories · {mode} mode · {_dur}ms"
+            if recent_count_val is not None:
+                header += f" · {recent_count_val} recent + {neighbor_count_val} neighbors"
+            lines.append(header)
+            lines.append("")
+
+            for i, m in enumerate(memories):
+                mtype = m.type.value if hasattr(m.type, 'value') else m.type
+                rel = round(scores[i], 4)
+                lines.append(f"[{mtype}] {m.content}")
+                meta_parts = []
+                if m.file_path:
+                    meta_parts.append(f"file: {m.file_path}")
+                meta_parts.append(f"relevance: {rel}")
+                meta_parts.append(f"id: {m.id}")
+                lines.append("  " + " · ".join(meta_parts))
+                lines.append("")
+
+            return "\n".join(lines)
         except ValueError as e:
             _dur = int((_time.monotonic_ns() - _t0) / 1_000_000)
             await _log_op(db, "remember", project=project,

{mango_brain-3.3.2 → mango_brain-3.3.4}/server/retrieval.py

@@ -185,10 +185,13 @@ class RetrievalEngine:
                 candidates.append((score / max(m.token_count, 1), score, m))
         candidates.sort(key=lambda x: x[0], reverse=True)
 
+        from server.config import RECENT_MAX_RESULTS
         selected: list[Memory] = []
         scores: list[float] = []
         total_tokens = 0
         for _, score, m in candidates:
+            if len(selected) >= RECENT_MAX_RESULTS:
+                break
             if total_tokens + m.token_count > budget:
                 continue
             selected.append(m)

mango_brain-3.3.4/server/rules/mangobrain-remember.md

@@ -0,0 +1,158 @@
+# MangoBrain — Remember Query Strategy
+
+You have access to the `remember` MCP tool to retrieve relevant memories from the project.
+Use it often, not just at the start of a task. Memories contain gotchas, patterns, decisions, and references that code alone doesn't tell you.
+
+## Query Language
+
+**All remember() queries MUST use English keywords**, regardless of session language.
+Memories are stored in English — queries in other languages degrade retrieval by ~15-20%.
+
+```
+GOOD: remember(query="formatPrice cents euros conversion gotcha", ...)
+BAD:  remember(query="formattazione prezzi conversione centesimi", ...)
+```
+
+Always translate concepts before querying. The conversation stays in the user's language, but queries go to the DB in English.
+
+## When to use remember
+
+- **Task/session start**: broad context (see multi-query strategy below)
+- **Before touching an unfamiliar area**: targeted quick query
+- **When you find a bug**: quick query to check for known patterns
+- **Before creating a component/utility**: quick query to verify if something similar already exists
+- **When making an architectural decision**: quick query for precedents
+- **End of task**: remember(mode="recent") to check WIP and context for mem-manager
+
+## Multi-query strategy (task start)
+
+Do NOT make a single generic query. Use **1 deep + N quick**:
+
+### 1. Read the task and identify 2-4 distinct technical areas
+
+### 2. 1x deep — big picture
+```
+remember(query="[max 10 keywords from the task]", mode="deep", project="{PROJECT}")
+```
+Captures: cross-cutting patterns, conventions, recurring gotchas. ~20 results.
+
+### 3. 2-4x quick — one per technical area
+```
+remember(query="[specific names: components, hooks, services, files]", mode="quick", project="{PROJECT}")
+```
+Captures: specific details per cluster. ~6 results each.
+
+### Why this works
+Each query pulls from a different cluster in the associative graph. A single generic deep query hits 1-2 clusters and misses the rest. 3 targeted quick queries cover 3 different clusters.
+
+## How to formulate queries
+
+### Keywords > natural language
+```
+GOOD: "formatPrice cents euros conversion gotcha"
+BAD:  "how does price formatting work in the system"
+```
+
+### Always use proper names
+Use component names, hooks, services, files, utilities when you know them:
+```
+GOOD: "useStripeConnect ConnectAccountManagement onboarding embedded"
+BAD:  "the Stripe payment onboarding system"
+```
+
+### Mix technical + domain
+```
+GOOD: "booking wizard localStorage state persistence gotcha"
+BAD:  "issues with the booking wizard"
+```
+
+## Quick vs Deep vs Recent
+
+| Mode | Results | Graph | When |
+|------|---------|-------|------|
+| deep | ~20 | full (alpha=0.3) | Task start, big picture |
+| quick | ~6 | light (alpha=0.15) | Mid-task, specific areas, lookup |
+| recent | ~15 + neighbors | by time | Session start, understand WIP |
+
+## Work context strategy
+
+### Session start (always)
+```
+remember(mode="recent", project="{PROJECT}", limit=15, k_neighbors=2)
+```
+Returns: last 15 memories + graph-connected context. Understand WIP, blockers, recent decisions.
+
+### Mid-task: about to touch a new area
+```
+remember(query="[file names, components, concepts of the area]", mode="quick", project="{PROJECT}")
+```
+
+### Mid-task: found a bug
+```
+remember(query="[bug keywords + area + pattern]", mode="quick", project="{PROJECT}")
+```
+
+### End of task / pre-mem-manager
+```
+remember(mode="recent", project="{PROJECT}")
+```
+Check WIP and context to pass to mem-manager for sync.
+
+## Real examples
+
+### Task: "Fix wrong price in booking wizard"
+```
+deep:  "booking wizard UX fix price bug mobile layout"
+quick: "formatPrice cents euros conversion serializeBooking gotcha"
+quick: "OrderWizard steps PaymentStep SummaryStep"
+```
+
+### Task: "Refactor profile + shared payments"
+```
+deep:  "account profile refactor shared components owner teacher payments Stripe"
+quick: "ProfiloPage TeacherAccountPage structure password removal"
+quick: "Stripe Connect onboarding useStripeConnect ConnectAccountManagement"
+quick: "User model schema getMe provider stripeAccountId Prisma"
+quick: "Google Calendar routes sync disconnect auth calendarSyncJob"
+```
+
+### Mid-task: about to touch the email system
+```
+quick: "email Resend templates transactional React Email service"
+```
+
+### Mid-task: found a price bug
+```
+quick: "price double-division cents euros formatPrice formatMoneyValue"
+```
+
+### Generic session start
+```
+recent: limit=15, k_neighbors=2
+deep:   "project overview architecture current state WIP"
+```
+
+## How to interpret results
+
+Each memory returned by `remember` has:
+- **type**: episodic (specific event, dated), semantic (fact/architecture, stable), procedural (how-to, instructions)
+- **tags**: thematic cluster (bug, gotcha, convention, reference, pattern, decision, state, wip...)
+- **relevance score**: semantic proximity to query (>0.7 high, 0.4-0.7 medium, <0.4 low)
+- **file_path**: if present, the file it refers to — verify it still exists before trusting it
+- **age**: old episodic memories may be stale, semantic ones stay valid longer
+
+### How to weigh memories by tag
+
+| Tag | Priority | How to use |
+|-----|----------|------------|
+| **gotcha**, **bug** | High | Warnings from past experience. Read carefully before touching that area. |
+| **convention**, **pattern** | High | Follow them unless current code explicitly contradicts them. |
+| **reference** | Medium | Point to utilities/hooks/services. Verify they still exist before using. |
+| **decision** | Medium | Contain the WHY. Respect the decision or discuss with user if you want to change it. |
+| **state**, **wip** | Context | Inform about ongoing work. Most recent ones are most relevant. |
+
+### Stale memory signals
+
+- Memory says "file X uses pattern Y" but code shows otherwise → flag as potentially stale
+- Old episodic memory (months) about an area that was rewritten → probably no longer relevant
+- Memory with file_path that no longer exists → file was renamed or removed

mango_brain-3.3.4/server/rules/mangobrain-workflow.md

@@ -0,0 +1,103 @@
+# MangoBrain — Workflow Integration
+
+MangoBrain provides persistent associative memory across Claude Code sessions. This rule describes how and when to use it in daily workflow.
+
+## Server
+
+MangoBrain requires the server to be running. If the user asks to start it or if MCP tools are not responding:
+```
+mangobrain serve --api    # start server + dashboard (http://localhost:3101)
+```
+Run it in the background. If the server is already running, no need to restart.
+
+## Overview
+
+MangoBrain is not a file to read at the start. It's an active retrieval system: ask for what you need, when you need it. Memories contain past bugs, architectural decisions, patterns, gotchas, references to utilities and components — knowledge that code alone doesn't communicate.
+
+## Query Language
+
+**All remember() queries MUST use English keywords**, regardless of session language.
+Memories are stored in English — queries in other languages degrade retrieval by ~15-20%. The conversation stays in the user's language, but queries go to the DB in English.
+
+## Integration with /discuss
+
+**INTAKE** (start of discussion):
+1. `remember(mode="recent")` — recent context, WIP, decisions
+2. Identify 2-3 technical areas of the topic
+3. `remember(mode="deep", query="[topic in max 10 keywords]")` — big picture
+4. 1-2x `remember(mode="quick", query="[specific names per area]")` — targeted details
+5. Show relevant memories to the user as context
+
+**EXPLORE** (code analysis):
+- The analyzer explores the code, enriched by memory context
+- If an unexplored area emerges, do a quick query before responding
+
+**BRAINSTORM** (discussion):
+- Memories inform the brainstorm:
+  - Past bugs in the same area: "careful, last time..."
+  - Architectural decisions: "this was decided because..."
+  - Consolidated patterns: "the pattern used elsewhere is..."
+
+## Integration with /task
+
+**ANALYZE** (task start):
+1. `remember(mode="recent")` — WIP, context
+2. Multi-query strategy (1 deep + N quick) — see mangobrain-remember.md
+3. Memories guide the analysis: you already know gotchas, patterns, available utilities
+
+**Mid-task** (during development):
+- Before touching a new area: quick query
+- When you find a bug: quick query for known patterns
+- Before creating a component: quick query to check if something similar exists
+
+**CLOSE** (end of task):
+The main orchestrator spawns the **mem-manager** as a sub-agent with:
+- Summary of work done
+- List of modified files (git diff)
+- Decisions made
+- WIP/blockers
+
+The mem-manager autonomously:
+1. Creates memories for significant work (memorize)
+2. Syncs changed files with existing memories (sync_codebase + update_memory)
+3. Records WIP if present (memorize with tags "state", "wip")
+
+## Free sessions (without /task)
+
+For sessions without /task (discussions, explorations, quick fixes):
+- Use `remember` during the session as described above
+- At end of session, use **/memorize** to sync work to memory
+- /memorize prepares a summary and spawns the mem-manager
+
+## Periodic maintenance
+
+| Activity | Frequency | Skill | What it does |
+|----------|-----------|-------|--------------|
+| Elaboration | Weekly | /elaborate | Consolidates, creates edges, abstractions, deprecates duplicates |
+| Health check | Monthly | /health-check | Diagnosis of structure + content, targeted fixes |
+| Smoke test | Post-init, post-elaboration | /smoke-test | Verifies retrieval quality with test queries |
+
+## The mem-manager agent
+
+The mem-manager is a specialized sub-agent for memory management. It's not interactive — it's spawned by main with precise context and operates autonomously.
+
+**What it does:**
+- Creates atomic memories (2-5 lines, English, self-contained)
+- Classifies: episodic (events), semantic (facts), procedural (how-to)
+- Tags: 3-6 lowercase tags
+- Adds relationships between memories (relates_to, depends_on, caused_by)
+- Syncs changed files with existing memories
+- Records WIP for the next session
+
+**What it does NOT do:**
+- Does not interact with the user
+- Does not make architectural decisions
+
+## When NOT to use memory
+
+- **Purely mechanical tasks**: "rename this variable", "add an import"
+- **One-line fixes**: if the fix is obvious and there's no lesson to learn
+- **Routine operations**: npm install, docker restart, git merge
+- **When context is entirely in the task**: if the task is self-contained and doesn't touch complex areas
+
+The rule: if the work doesn't produce reusable knowledge, it doesn't need to be memorized.

mango_brain-3.3.4/server/work/rules/mangobrain-remember-work.md

@@ -0,0 +1,79 @@
+# MangoBrain Work — Query Strategy
+
+You have access to the `remember` MCP tool to retrieve information from the project.
+Use it often. Memory contains brand decisions, feedback, patterns, target insights, and references that documents alone don't communicate.
+
+## When to use remember
+
+- **Session start**: recent context + project overview
+- **Before creating content**: query brand, tone, audience for that channel
+- **When the user asks something new**: check for past decisions
+- **When the user gives feedback**: check if it's a pattern (have they said the same thing before?)
+- **End of session**: `remember(mode="recent")` to confirm what to save
+
+## Multi-query strategy (session start)
+
+### 1. Recent — where we left off
+```
+remember(mode="recent", project="{PROJECT}", limit=10, k_neighbors=2)
+```
+
+### 2. Deep — broad context on the topic
+```
+remember(query="[5-10 keywords from the requested topic]", mode="deep", project="{PROJECT}")
+```
+
+### 3. Quick — specific areas
+```
+remember(query="[brand tone voice guidelines]", mode="quick", project="{PROJECT}")
+remember(query="[Instagram format carousel content rules]", mode="quick", project="{PROJECT}")
+```
+
+## Query Language
+
+**All remember() queries MUST use English keywords**, regardless of session language.
+Memories are stored in English — queries in other languages degrade retrieval by ~15-20%.
+
+```
+GOOD: remember(query="Instagram post engagement CTA caption", ...)
+BAD:  remember(query="post Instagram coinvolgimento didascalia", ...)
+```
+
+Always translate concepts before querying. The conversation stays in the user's language, but queries go to the DB in English.
+
+## How to formulate queries
+
+### Keywords > natural language
+```
+GOOD: "Instagram carousel CTA engagement caption hashtags"
+BAD:  "how should I write Instagram posts"
+```
+
+### Domain proper names
+```
+GOOD: "target musician band rehearsal studio booking"
+BAD:  "our target audience"
+```
+
+### Mix area + specific
+```
+GOOD: "competitor pricing studio booking platform market"
+BAD:  "competitive analysis"
+```
+
+## Cross-project (if available)
+
+If the project has an associated Code memory, you can pull product information:
+```
+remember(query="feature booking user flow value proposition", project="{CODE_PROJECT}", mode="quick")
+```
+
+**RULE**: always translate to non-technical language before using or showing this information to the user.
+
+## Quick vs Deep vs Recent
+
+| Mode | Results | When |
+|------|---------|------|
+| deep | ~20 | Session start, strategy, broad analysis |
+| quick | ~6 | Mid-session, specific area, quick lookup |
+| recent | ~15 | Session start, understand WIP and state |

mango_brain-3.3.4/server/work/rules/mangobrain-workflow-work.md

@@ -0,0 +1,48 @@
+# MangoBrain Work — Workflow
+
+MangoBrain provides persistent memory across sessions. This rule describes how to use it in daily workflow.
+
+## Principle
+
+Memory is not a file to consult. It's an active system: ask for what you need, when you need it. It contains brand decisions, user feedback, target insights, content patterns, past mistakes — knowledge that documents alone don't transmit.
+
+## Query Language
+
+**All remember() queries MUST use English keywords**, regardless of session language.
+Memories are stored in English — queries in other languages degrade retrieval by ~15-20%. The conversation stays in the user's language, but queries go to the DB in English.
+
+## Integration with /brief
+
+**INTAKE**: remember recent + deep + quick → full context before asking questions
+**CLARIFICATION**: use context to NOT ask things you already know
+**MATERIAL EXPLORATION**: search documents AND memory
+**BRIEF**: the brief is informed by project history
+
+## Integration with /create
+
+**RESEARCH**: the Researcher pulls from memory for brand, tone, audience, past content
+**CREATION**: the Creator receives pre-digested context (does not query)
+**REVIEW**: the Reviewer compares against past decisions and historical feedback
+**CLOSE**: the Mem-manager saves new decisions, feedback, patterns
+
+## Free sessions
+
+For sessions without /create (brainstorm, analysis, strategy):
+- Use `remember` during the session
+- At end of session: `/memorize-work`
+
+## What to memorize and what not to
+
+### YES — produces reusable knowledge
+- Brand decision ("we use teal as primary color")
+- User feedback ("the tone was too formal, prefers casual")
+- Target insight ("musicians under 25 prefer Reels over static posts")
+- Content pattern ("carousels with a question in the title perform better")
+- Strategic choice ("for launch we focus on Instagram + TikTok, no LinkedIn")
+- Mistake not to repeat ("the last CTA was too aggressive")
+
+### NO — not worth memorizing
+- Discarded drafts and intermediate iterations
+- Information already in rule files (those are auto-loaded every session)
+- Generic facts not specific to the project
+- Content already produced (the file exists, no need to duplicate it in memory)