dulus 0.2.0__py3-none-any.whl

memory/tools.py

@@ -0,0 +1,408 @@
+"""Memory tool registrations: MemorySave, MemoryDelete, MemorySearch.
+
+Importing this module registers the three tools into the central registry.
+"""
+from __future__ import annotations
+
+from datetime import datetime
+
+from tool_registry import ToolDef, register_tool
+from .store import MemoryEntry, save_memory, delete_memory, load_index, check_conflict, touch_last_used
+from .context import find_relevant_memories
+from .scan import scan_all_memories, format_memory_manifest
+from .sessions import search_session_history
+
+
+# ── Tool implementations ───────────────────────────────────────────────────
+
+def _memory_save(params: dict, config: dict) -> str:
+    """Save or update a persistent memory entry, with conflict detection."""
+    scope = params.get("scope", "user")
+    entry = MemoryEntry(
+        name=params["name"],
+        description=params["description"],
+        type=params["type"],
+        content=params["content"],
+        created=datetime.now().strftime("%Y-%m-%d"),
+        hall=params.get("hall", ""),
+        confidence=float(params.get("confidence", 1.0)),
+        source=params.get("source", "user"),
+        conflict_group=params.get("conflict_group", ""),
+    )
+
+    conflict = check_conflict(entry, scope=scope)
+    save_memory(entry, scope=scope)
+
+    # ── Auto-mine into MemPalace (fire-and-forget) ──
+    # mempalace skips already-filed files, so only the new MD gets indexed.
+    if config.get("mem_palace", True) and scope == "user":
+        try:
+            import subprocess as _sp, sys as _sys, os as _os
+            from pathlib import Path as _Path
+            _mem_dir = _Path.home() / ".dulus" / "memory"
+            _env = {**_os.environ, "PYTHONIOENCODING": "utf-8", "PYTHONUTF8": "1"}
+            _sp.Popen(
+                [_sys.executable, "-X", "utf8", "-m", "mempalace", "mine",
+                 str(_mem_dir), "--wing", "memory", "--agent", "dulus"],
+                stdout=_sp.DEVNULL, stderr=_sp.DEVNULL,
+                env=_env,
+                creationflags=getattr(_sp, "CREATE_NO_WINDOW", 0),
+            )
+        except Exception:
+            pass  # never block save on mining failure
+
+    scope_label = "project" if scope == "project" else "user"
+    hall_label = f"/{entry.hall}" if entry.hall else ""
+    msg = f"Memory saved: '{entry.name}' [{entry.type}{hall_label}/{scope_label}]"
+    if entry.confidence < 1.0:
+        msg += f" (confidence: {entry.confidence:.0%})"
+    if conflict:
+        msg += (
+            f"\n⚠ Replaced conflicting memory"
+            f" (was {conflict['existing_source']}-sourced, {conflict['existing_confidence']:.0%} confidence,"
+            f" written {conflict['existing_created'] or 'unknown date'})."
+            f" Old content: {conflict['existing_content'][:120]}"
+            f"{'...' if len(conflict['existing_content']) > 120 else ''}"
+        )
+    return msg
+
+
+def _memory_delete(params: dict, config: dict) -> str:
+    """Delete a persistent memory entry by name."""
+    name = params["name"]
+    scope = params.get("scope", "user")
+    delete_memory(name, scope=scope)
+    return f"Memory deleted: '{name}' (scope: {scope})"
+
+
+def _memory_search(params: dict, config: dict) -> str:
+    """Search memories by keyword query with optional AI relevance filtering.
+
+    Results are ranked by: confidence × recency (30-day exponential decay).
+    """
+    import math, time as _time
+    query = params["query"]
+    use_ai = params.get("use_ai", False)
+    
+    if config.get("ULTRA_SEARCH") in (1, "1", True, "true"):
+        params["include_sessions"] = True
+        max_results = max(params.get("max_results", 5), 100)
+    else:
+        max_results = params.get("max_results", 5)
+
+    results = find_relevant_memories(
+        query, max_results=max_results * 3, use_ai=use_ai, config=config
+    )
+
+    if not results:
+        return f"No memories found matching '{query}'."
+
+    # Re-rank by confidence × recency score
+    now = _time.time()
+    for r in results:
+        age_days = max(0, (now - r["mtime_s"]) / 86400)
+        recency = math.exp(-age_days / 30)   # half-life ≈ 21 days
+        r["_rank"] = r.get("confidence", 1.0) * recency
+    results.sort(key=lambda r: r["_rank"], reverse=True)
+    results = results[:max_results]
+
+    # Touch last_used_at for returned memories
+    for r in results:
+        if r.get("file_path"):
+            touch_last_used(r["file_path"])
+
+    lines = [f"Found {len(results)} relevant memory/memories for '{query}':", ""]
+    for r in results:
+        freshness = f"  ⚠ {r['freshness_text']}" if r["freshness_text"] else ""
+        conf = r.get("confidence", 1.0)
+        src = r.get("source", "user")
+        hall_tag = f"/{r['hall']}" if r.get("hall") else ""
+        meta_tag = ""
+        if conf < 1.0 or src != "user":
+            meta_tag = f"  [conf:{conf:.0%} src:{src}]"
+        lines.append(
+            f"[{r['type']}{hall_tag}/{r['scope']}] {r['name']}{meta_tag}\n"
+            f"  {r['description']}\n"
+            f"  {r['content'][:200]}{'...' if len(r['content']) > 200 else ''}"
+            f"{freshness}"
+        )
+
+    # ── Part 2: Session history search ───────────────────────────────────
+    # Heuristic: If we found few results (< 3), automatically search session history
+    # unless include_sessions was explicitly False.
+    should_search_sessions = params.get("include_sessions")
+
+    if should_search_sessions:
+        sess_results = search_session_history(query, max_results=max_results)
+        if sess_results:
+            lines.append("\n" + "─" * 40)
+            lines.append(f"Historical Session Matches ({len(sess_results)} sessions):")
+            for sr in sess_results:
+                lines.append(f"\nSession {sr['session_id']} ({sr['saved_at']})")
+                for h in sr["hits"]:
+                    role_lbl = "User" if h["role"] == "user" else "Dulus"
+                    lines.append(f"  [{role_lbl}] {h['snippet']}")
+
+    # ── Part 3: Offloaded Jobs Search ────────────────────────────────────
+    try:
+        from pathlib import Path
+        import json
+        jobs_dir = Path.home() / ".dulus" / "jobs"
+        if jobs_dir.is_dir():
+            job_matches = []
+            q_lower = query.lower()
+            q_words = [w.strip() for w in q_lower.split() if w.strip()]
+            for fp in jobs_dir.glob("*.json"):
+                try:
+                    with open(fp, "r", encoding="utf-8") as f:
+                        job = json.load(f)
+                    job_text = json.dumps(job, ensure_ascii=False).lower()
+                    # Allow fuzzy token matching across the JSON content
+                    if all(w in job_text for w in q_words):
+                        job_matches.append(job)
+                except Exception:
+                    pass
+            if job_matches:
+                lines.append("\n" + "─" * 40)
+                lines.append(f"Offloaded Background Jobs ({len(job_matches)} matches):")
+                job_matches.sort(key=lambda j: j.get("created_at", ""), reverse=True)
+                for j in job_matches[:max_results]:
+                    status = j.get("status", "unknown")
+                    lines.append(f"\nJob {j.get('id')} - Tool: {j.get('tool_name')} ({status})")
+                    if j.get("params"):
+                        lines.append(f"  Params: {json.dumps(j['params'], ensure_ascii=False)}")
+                    if j.get("result"):
+                        res = j["result"]
+                        if len(res) > 300:
+                            idx = res.lower().find(q_lower)
+                            if idx != -1:
+                                start = max(0, idx - 100)
+                                end = min(len(res), idx + 200)
+                                snippet = res[start:end].replace("\n", " ")
+                                lines.append(f"  Result snippet: ...{snippet}...")
+                            else:
+                                lines.append(f"  Result snippet: {res[:300]}...")
+                        else:
+                            lines.append(f"  Result: {res}")
+    except Exception:
+        pass
+
+    if not params.get("include_sessions") and not should_search_sessions:
+        lines.append("\n💡 Hint: No matches? Call MemorySearch again with `include_sessions=True` to search through all past session chat logs.")
+
+    if not lines[1:]: # Ensure we don't return an empty "Found 0" without hints
+        pass
+
+    return "\n".join(lines).strip()
+
+
+
+def _memory_list(params: dict, config: dict) -> str:
+    """List all memory entries with type, scope, age, confidence, and description."""
+    from .store import load_entries
+
+    scope_filter = params.get("scope", "all")
+    scopes = ["user", "project"] if scope_filter == "all" else [scope_filter]
+
+    all_entries = []
+    for s in scopes:
+        all_entries.extend(load_entries(s))
+
+    if not all_entries:
+        return "No memories stored." if scope_filter == "all" else f"No {scope_filter} memories stored."
+
+    lines = [f"{len(all_entries)} memory/memories:"]
+    for e in all_entries:
+        conf_tag = f" conf:{e.confidence:.0%}" if e.confidence < 1.0 else ""
+        src_tag = f" src:{e.source}" if e.source and e.source != "user" else ""
+        cg_tag = f" grp:{e.conflict_group}" if e.conflict_group else ""
+        hall_tag = f" hall:{e.hall}" if e.hall else ""
+        meta = f"{conf_tag}{src_tag}{cg_tag}{hall_tag}".strip()
+        tag = f"[{e.type:9s}|{e.scope:7s}]"
+        lines.append(f"  {tag} {e.name}{(' — ' + meta) if meta else ''}")
+        if e.description:
+            lines.append(f"    {e.description}")
+    return "\n".join(lines)
+
+
+# ── Tool registrations ─────────────────────────────────────────────────────
+
+register_tool(ToolDef(
+    name="MemorySave",
+    schema={
+        "name": "MemorySave",
+        "description": (
+            "Save a persistent memory entry as a markdown file with frontmatter. "
+            "Use for information that should persist across conversations: "
+            "user preferences, feedback/corrections, project context, or external references. "
+            "Do NOT save: code patterns, architecture, git history, or task state.\n\n"
+            "For feedback/project memories, structure content as: "
+            "rule/fact, then **Why:** and **How to apply:** lines.\n\n"
+            "Optionally categorize with a 'hall': facts (decisions), events (milestones), "
+            "discoveries (insights), preferences (habits), advice (recommendations)."
+        ),
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "description": "Human-readable name (becomes the filename slug)",
+                },
+                "type": {
+                    "type": "string",
+                    "enum": ["user", "feedback", "project", "reference"],
+                    "description": (
+                        "user=preferences/role, feedback=guidance on how to work, "
+                        "project=ongoing work/decisions, reference=external system pointers"
+                    ),
+                },
+                "hall": {
+                    "type": "string",
+                    "enum": ["facts", "events", "discoveries", "preferences", "advice"],
+                    "description": (
+                        "Categorize HOW this memory should be used. "
+                        "facts=decisions locked in, events=milestones/timeline, "
+                        "discoveries=insights/breakthroughs, preferences=habits/likes, "
+                        "advice=recommendations/solutions. Optional — omit if unsure."
+                    ),
+                },
+                "description": {
+                    "type": "string",
+                    "description": "Short one-line description (used for relevance decisions — be specific)",
+                },
+                "content": {
+                    "type": "string",
+                    "description": "Body text. For feedback/project: rule/fact + **Why:** + **How to apply:**",
+                },
+                "scope": {
+                    "type": "string",
+                    "enum": ["user", "project"],
+                    "description": (
+                        "'user' (default) = ~/.dulus/memory/ shared across projects; "
+                        "'project' = .dulus/memory/ local to this project"
+                    ),
+                },
+                "confidence": {
+                    "type": "number",
+                    "description": (
+                        "Reliability score 0.0–1.0. Default 1.0 = explicit user statement. "
+                        "Use ~0.8 for inferred preferences, ~0.6 for uncertain facts."
+                    ),
+                },
+                "source": {
+                    "type": "string",
+                    "enum": ["user", "model", "tool"],
+                    "description": (
+                        "Origin of this memory: 'user' (default, explicit statement), "
+                        "'model' (inferred by AI), 'tool' (from tool output)."
+                    ),
+                },
+                "conflict_group": {
+                    "type": "string",
+                    "description": (
+                        "Optional tag grouping related or potentially conflicting memories "
+                        "(e.g. 'writing_style'). Helps with conflict resolution."
+                    ),
+                },
+            },
+            "required": ["name", "type", "description", "content"],
+        },
+    },
+    func=_memory_save,
+    read_only=False,
+    concurrent_safe=False,
+))
+
+register_tool(ToolDef(
+    name="MemoryDelete",
+    schema={
+        "name": "MemoryDelete",
+        "description": "Delete a persistent memory entry by name.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "name": {"type": "string", "description": "Name of the memory to delete"},
+                "scope": {
+                    "type": "string",
+                    "enum": ["user", "project"],
+                    "description": "Scope to delete from (default: 'user')",
+                },
+            },
+            "required": ["name"],
+        },
+    },
+    func=_memory_delete,
+    read_only=False,
+    concurrent_safe=False,
+))
+
+register_tool(ToolDef(
+    name="MemorySearch",
+    schema={
+        "name": "MemorySearch",
+        "description": (
+            "Search persistent memories using fuzzy token matching. Returns entries ranked by "
+            "relevance (name/description weighted higher) with content preview and staleness "
+            "warnings. Searches are 100% case-insensitive and support partial string matches automatically "
+            "- do NOT query multiple casing variations. "
+            "Set use_ai=true for AI-powered re-ranking (costs a small API call). "
+            "Optionally filter by hall to narrow results."
+        ),
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "query": {"type": "string", "description": "Search query (supports fuzzy matching)"},
+                "max_results": {
+                    "type": "integer",
+                    "description": "Maximum results to return (default: 5). 💡 CRITICAL: To search deep session history exhaustively, you MUST set this to a high number (e.g. 50 or 100), otherwise it will cap at 5 sessions!",
+                },
+                "use_ai": {
+                    "type": "boolean",
+                    "description": "Use AI relevance ranking (default: false = fuzzy match only)",
+                },
+                "scope": {
+                    "type": "string",
+                    "enum": ["user", "project", "all"],
+                    "description": "Which scope to search (default: 'all')",
+                },
+                "hall": {
+                    "type": "string",
+                    "enum": ["facts", "events", "discoveries", "preferences", "advice"],
+                    "description": "Optional: only search within this hall category",
+                },
+                "include_sessions": {
+                    "type": "boolean",
+                    "description": "Include matches from historical session logs and offline background jobs. REQUIRED if the user asks for exhaustive search, 'past searches', 'history', 'previous sessions', 'antiguo', 'global', 'total', 'exhaustiva', or 'histórica'. (default: false)",
+                },
+            },
+            "required": ["query"],
+        },
+    },
+    func=_memory_search,
+    read_only=True,
+    concurrent_safe=True,
+))
+
+register_tool(ToolDef(
+    name="MemoryList",
+    schema={
+        "name": "MemoryList",
+        "description": (
+            "List all memory entries with type, scope, age, and description. "
+            "Useful for reviewing what's been remembered before deciding to save or delete."
+        ),
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "scope": {
+                    "type": "string",
+                    "enum": ["user", "project", "all"],
+                    "description": "Which scope to list (default: 'all')",
+                },
+            },
+        },
+    },
+    func=_memory_list,
+    read_only=True,
+    concurrent_safe=True,
+))

memory/types.py

@@ -0,0 +1,114 @@
+"""Memory type and hall taxonomy with system-prompt guidance text.
+
+Four types capture context NOT derivable from the current project state.
+Code patterns, architecture, git history, and file structure are derivable
+(via grep/git/CLAUDE.md) and should NOT be saved as memories.
+
+Halls categorize memories by their nature (orthogonal to type):
+  facts, events, discoveries, preferences, advice.
+"""
+
+MEMORY_TYPES = ["user", "feedback", "project", "reference"]
+
+# Halls categorize HOW information should be used, while types
+# categorize WHAT the information is about.
+MEMORY_HALLS = ["soul", "facts", "events", "discoveries", "preferences", "advice"]
+
+MEMORY_HALL_DESCRIPTIONS: dict[str, str] = {
+    "soul": "Identity, core relationship, and 'spirit' of the agent.",
+    "facts": "Decisions locked in, choices made, truths established.",
+    "events": "Sessions, milestones, debugging breakthroughs, timeline entries.",
+    "discoveries": "New insights, breakthroughs, non-obvious findings.",
+    "preferences": "Habits, likes, opinions, working-style choices.",
+    "advice": "Recommendations, solutions, guidance for future reference.",
+}
+
+# Condensed per-type guidance (used in system prompt injection)
+MEMORY_TYPE_DESCRIPTIONS: dict[str, str] = {
+    "user": (
+        "Information about the user's role, goals, responsibilities, and knowledge. "
+        "Helps tailor future behavior to the user's preferences."
+    ),
+    "feedback": (
+        "Guidance the user has given about how to approach work — both what to avoid "
+        "and what to keep doing. Lead with the rule, then **Why:** and **How to apply:**."
+    ),
+    "project": (
+        "Ongoing work, goals, bugs, or incidents not derivable from code or git history. "
+        "Lead with the fact/decision, then **Why:** and **How to apply:**. "
+        "Always convert relative dates to absolute dates."
+    ),
+    "reference": (
+        "Pointers to external systems (issue trackers, dashboards, Slack channels, docs)."
+    ),
+}
+
+# What NOT to save (mirrors Claude Code source)
+WHAT_NOT_TO_SAVE = """\
+## What NOT to save in memory
+- Code patterns, conventions, architecture, file paths, or project structure — derivable from the codebase.
+- Git history, recent changes, who-changed-what — use `git log` / `git blame`.
+- Debugging solutions or fix recipes — the fix is in the code; the commit message has context.
+- Anything already documented in CLAUDE.md files.
+- Ephemeral task details: in-progress work, temporary state, current conversation context.
+
+These exclusions apply even when explicitly asked. If asked to save a PR list or activity summary,
+ask what was *surprising* or *non-obvious* — that is the part worth keeping."""
+
+# Memory format example (frontmatter)
+MEMORY_FORMAT_EXAMPLE = """\
+```markdown
+---
+name: {{memory name}}
+description: {{one-line description — used to decide relevance, so be specific}}
+type: {{user | feedback | project | reference}}
+---
+
+{{memory content — for feedback/project types: rule/fact, then **Why:** and **How to apply:** lines}}
+```"""
+
+# Full guidance injected into the system prompt
+MEMORY_SYSTEM_PROMPT = """\
+## Memory system
+
+You have a persistent, file-based memory system. Memories are stored as markdown files with
+YAML frontmatter. Build this up over time so future conversations have context about the user,
+their preferences, and the work you're doing together.
+
+**Types** (save only what cannot be derived from the codebase):
+- **user** — role, goals, knowledge, preferences
+- **feedback** — guidance on how to work (corrections AND confirmations of non-obvious approaches)
+- **project** — ongoing work, decisions, deadlines not in git history
+- **reference** — pointers to external systems (Linear, Grafana, Slack, etc.)
+
+**Halls** (categorize HOW the memory should be used):
+- **soul** — identity, core relationship, and 'spirit' of the agent (Sacred)
+- **facts** — decisions locked in, choices made, truths established
+- **events** — sessions, milestones, debugging breakthroughs, timeline entries
+- **discoveries** — new insights, breakthroughs, non-obvious findings
+- **preferences** — habits, likes, opinions, working-style choices
+- **advice** — recommendations, solutions, guidance for future reference
+
+Halls are orthogonal to types. Example: a "feedback" memory about "always use black for formatting"
+would go in the "preferences" hall. A "project" memory about "migrated auth to Clerk on 2026-03"
+would go in the "events" hall. If unsure, omit the hall — it's optional.
+
+**When to save**: If the user corrects you, confirms an approach, or shares context that should
+persist beyond this conversation. For feedback: save corrections AND quiet confirmations.
+
+**Body structure for feedback/project**: Lead with the rule/fact, then:
+  **Why:** (reason given) | **How to apply:** (when this guidance kicks in)
+
+**Format**:
+{format_example}
+
+**Saving is two steps**:
+1. Write the memory to its own file (e.g. `feedback_testing.md`) using MemorySave.
+2. The index (MEMORY.md) is updated automatically.
+
+**What NOT to save**: code patterns, architecture, git history, debugging fixes,
+anything already in CLAUDE.md, or ephemeral task state.
+
+**Before recommending from memory**: A memory naming a file, function, or flag may be stale.
+Verify it still exists before acting on it. For current state, prefer `git log` or reading code.
+""".format(format_example=MEMORY_FORMAT_EXAMPLE)

memory/vector_search.py

@@ -0,0 +1,92 @@
+"""Vector search for memories using TF-IDF (pure Python, zero deps)."""
+from __future__ import annotations
+
+import math
+import re
+from collections import Counter
+from typing import List, Tuple, Dict
+
+_STOPWORDS = {
+    "the","a","an","is","are","was","were","be","been","being","to","of","and",
+    "in","on","at","by","for","with","about","from","up","down","out","off","over",
+    "under","again","further","then","once","here","there","when","where","why","how",
+    "all","any","both","each","few","more","most","other","some","such","no","nor",
+    "not","only","own","same","so","than","too","very","can","will","just","should",
+    "now","this","that","these","those","it","its","as","or","if","have","has","had",
+    "do","does","did","doing","done","get","use","make","go","see","know","take",
+    "come","think","say","also","back","after","two","way","even","new","want",
+    "because","first","well","any","work","may","give","look","find","day","could",
+    "long","great","world","year","still","might","last","right","old","put","around",
+    "every","part","much","el","la","lo","los","las","un","una","es","son","fue",
+    "ser","sido","siendo","de","y","en","por","para","con","sobre","entre","hacia",
+    "durante","antes","después","desde","hasta","que","quien","cual","cuando","donde",
+    "como","porque","si","pero","o","ya","muy","mas","más","todo","todos","cada",
+    "alguno","poco","muchos","mucho","muchas","otro","otros","este","esta","esto",
+    "estos","estas","ese","esa","eso","esos","esas","aqui","alli","allí","ahora",
+    "entonces","aun","aún","bien","mal","tan","tanto","tanta","asi","así","ni",
+    "sino","sin","solo","solamente","mismo","mientras","ademas","además","tambien",
+    "también","luego","sí","no","nunca","siempre","jamás","hace","hacer","hecho",
+    "tenido","tenía","tenemos","tienes","tengo","haber","hay","está","estan",
+    "estoy","era","eran","fui","fuimos","dar","dado","decir","dicho","ir","voy",
+    "va","vengo","viene","ver","vi","saber","sé","creo","poder","puedo","puede",
+    "querer","quiero","parecer","parece","deber","debo","debe","pensar","pienso",
+}
+
+
+def _tokenize(text: str) -> List[str]:
+    tokens = re.findall(r"[a-z0-9]+", text.lower())
+    return [t for t in tokens if t not in _STOPWORDS and len(t) > 2]
+
+
+def _tfidf_vectors(docs: List[str]) -> Tuple[List[Counter], Dict[str, int]]:
+    vocab: Dict[str, int] = {}
+    doc_tokens: List[List[str]] = []
+    for doc in docs:
+        tokens = _tokenize(doc)
+        doc_tokens.append(tokens)
+        for t in set(tokens):
+            vocab[t] = vocab.get(t, 0) + 1
+    n = len(docs)
+    vectors: List[Counter] = []
+    for tokens in doc_tokens:
+        tf = Counter(tokens)
+        vec = Counter()
+        for term, count in tf.items():
+            idf = math.log(n / (1 + vocab[term]))
+            vec[term] = count * idf
+        vectors.append(vec)
+    return vectors, vocab
+
+
+def _cosine(a: Counter, b: Counter) -> float:
+    dot = sum(a[t] * b[t] for t in a if t in b)
+    norm_a = math.sqrt(sum(v * v for v in a.values()))
+    norm_b = math.sqrt(sum(v * v for v in b.values()))
+    if norm_a == 0 or norm_b == 0:
+        return 0.0
+    return dot / (norm_a * norm_b)
+
+
+def search_similar_memories(query: str, memories: List[Tuple[str, str]], top_k: int = 5) -> List[Tuple[str, float]]:
+    """Search memories by semantic similarity.
+
+    Args:
+        query: search query text
+        memories: list of (id, content) tuples
+        top_k: number of results to return
+
+    Returns:
+        list of (memory_id, score) sorted by relevance
+    """
+    if not memories:
+        return []
+    contents = [content for _, content in memories]
+    vectors, _ = _tfidf_vectors(contents + [query])
+    query_vec = vectors[-1]
+    results = []
+    for i, (mem_id, _) in enumerate(memories):
+        score = _cosine(query_vec, vectors[i])
+        if score > 0.01:
+            results.append((mem_id, score))
+    results.sort(key=lambda x: x[1], reverse=True)
+    return results[:top_k]

multi_agent/__init__.py

@@ -0,0 +1,23 @@
+"""Multi-agent package for dulus.
+
+Provides:
+  - AgentDefinition  — typed agent definition (name, system_prompt, model, tools)
+  - SubAgentTask     — lifecycle-tracked task
+  - SubAgentManager  — thread-pool manager for spawning agents
+  - load_agent_definitions / get_agent_definition — agent registry
+"""
+from .subagent import (
+    AgentDefinition,
+    SubAgentTask,
+    SubAgentManager,
+    load_agent_definitions,
+    get_agent_definition,
+)
+
+__all__ = [
+    "AgentDefinition",
+    "SubAgentTask",
+    "SubAgentManager",
+    "load_agent_definitions",
+    "get_agent_definition",
+]