nowledge-mem-bub 0.1.0__tar.gz

nowledge_mem_bub-0.1.0/.gitignore

@@ -0,0 +1 @@
+__pycache__/

nowledge_mem_bub-0.1.0/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.0 (2026-03-12)
+
+Initial release — brings cross-tool knowledge into Bub.
+
+- 9 tools (`mem.search`, `mem.save`, `mem.context`, `mem.connections`, `mem.timeline`, `mem.forget`, `mem.threads`, `mem.thread`, `mem.status`) for searching and saving knowledge across all your AI tools
+- Hook-based integration: behavioural guidance via `system_prompt`, optional Working Memory injection via `load_state`, incremental thread capture via `save_state`
+- Two modes: default (agent-driven, on-demand) and session context (auto-inject Working Memory + recalled knowledge each turn)
+- Conversations in Bub flow into Nowledge Mem so other tools can find them
+- Pre-save deduplication check
+- Bundled `nowledge-mem` skill for agent self-guidance
+- Access Anywhere support via `~/.nowledge-mem/config.json` or `NMEM_API_URL` / `NMEM_API_KEY`

nowledge_mem_bub-0.1.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: nowledge-mem-bub
+Version: 0.1.0
+Summary: Nowledge Mem plugin for Bub — cross-ai context for your agent.
+Project-URL: Homepage, https://mem.nowledge.co
+Project-URL: Documentation, https://mem.nowledge.co/docs/integrations/bub
+Project-URL: Repository, https://github.com/nowledge-co/community/tree/main/nowledge-mem-bub-plugin
+Author-email: Nowledge Labs <hello@nowledge-labs.ai>
+License-Expression: Apache-2.0
+Keywords: agent,bub,knowledge-graph,memory,nowledge-mem
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.12
+Requires-Dist: bub>=0.3.0a1
+Description-Content-Type: text/markdown
+
+# Nowledge Mem — Bub Plugin
+
+> Bring your cross-tool knowledge into Bub, and share what you learn in Bub with every other tool.
+
+Bub records every session through its tape system. This plugin connects Bub to your personal knowledge graph in Nowledge Mem — so decisions from Claude Code, preferences from Cursor, and insights from ChatGPT are all searchable inside Bub. And what you learn in Bub flows back to every other tool.
+
+## Install
+
+```bash
+pip install nowledge-mem-bub
+```
+
+**Prerequisite:** `nmem` CLI must be in your PATH:
+
+```bash
+pip install nmem-cli    # or: pipx install nmem-cli
+nmem status             # verify connection
+```
+
+## Verify
+
+```bash
+uv run bub hooks        # should list nowledge_mem for system_prompt, load_state, save_state
+uv run bub run "what was I working on this week?"
+```
+
+If you have existing knowledge in Nowledge Mem, the agent should find it through `mem.search`.
+
+## Tools
+
+| Tool | What it does |
+|------|-------------|
+| `mem.search` | Search knowledge from all your tools. Supports label and date filters. |
+| `mem.save` | Save a decision, insight, or preference so any tool can find it. |
+| `mem.context` | Read today's Working Memory — focus areas, priorities, recent activity. |
+| `mem.connections` | Explore how a piece of knowledge relates to others across tools and time. |
+| `mem.timeline` | Recent activity grouped by day. |
+| `mem.forget` | Delete a memory by ID. |
+| `mem.threads` | Search past conversations from any tool. |
+| `mem.thread` | Fetch full messages from a conversation with pagination. |
+| `mem.status` | Connection and configuration diagnostics. |
+
+All tools work as Bub comma commands too: `,mem.search query=...`
+
+**Bundled skill:** The `nowledge-mem` skill teaches the agent when and how to use these tools effectively.
+
+## Configuration
+
+No config needed for local use. The plugin reads `~/.nowledge-mem/config.json` and environment variables automatically.
+
+| Variable | Default | What it does |
+|----------|---------|-------------|
+| `NMEM_SESSION_CONTEXT` | `false` | Inject Working Memory + recalled knowledge each turn |
+| `NMEM_SESSION_DIGEST` | `true` | Feed Bub conversations into Mem for other tools to find |
+| `NMEM_API_URL` | *(local)* | Remote Nowledge Mem server URL |
+| `NMEM_API_KEY` | *(none)* | API key for remote access |
+
+### Remote Access
+
+```json
+// ~/.nowledge-mem/config.json
+{
+  "apiUrl": "https://your-server:14242",
+  "apiKey": "your-key"
+}
+```
+
+Or use environment variables (`NMEM_API_URL`, `NMEM_API_KEY`), which override the config file.
+
+## Two Modes
+
+| Mode | Config | What happens |
+|------|--------|-------------|
+| **Default** | nothing | The agent searches and saves on demand. Conversations flow into Mem for other tools to find. |
+| **Session context** | `NMEM_SESSION_CONTEXT=1` | Working Memory and relevant knowledge injected automatically each turn. |
+
+Most users should start with the default.
+
+## Troubleshooting
+
+**nmem not found:** Install with `pip install nmem-cli` or `pipx install nmem-cli`.
+
+**Plugin not loading:** Run `uv run bub hooks` and check that `nowledge_mem` appears in the hook list.
+
+**Server not running:** Start the Nowledge Mem desktop app, or run `nmem status` for diagnostics.
+
+## Links
+
+- [Documentation](https://mem.nowledge.co/docs/integrations/bub)
+- [Discord](https://nowled.ge/discord)
+- [GitHub](https://github.com/nowledge-co/community/tree/main/nowledge-mem-bub-plugin)
+
+---
+
+Made with care by [Nowledge Labs](https://nowledge-labs.ai)

nowledge_mem_bub-0.1.0/README.md

@@ -0,0 +1,95 @@
+# Nowledge Mem — Bub Plugin
+
+> Bring your cross-tool knowledge into Bub, and share what you learn in Bub with every other tool.
+
+Bub records every session through its tape system. This plugin connects Bub to your personal knowledge graph in Nowledge Mem — so decisions from Claude Code, preferences from Cursor, and insights from ChatGPT are all searchable inside Bub. And what you learn in Bub flows back to every other tool.
+
+## Install
+
+```bash
+pip install nowledge-mem-bub
+```
+
+**Prerequisite:** `nmem` CLI must be in your PATH:
+
+```bash
+pip install nmem-cli    # or: pipx install nmem-cli
+nmem status             # verify connection
+```
+
+## Verify
+
+```bash
+uv run bub hooks        # should list nowledge_mem for system_prompt, load_state, save_state
+uv run bub run "what was I working on this week?"
+```
+
+If you have existing knowledge in Nowledge Mem, the agent should find it through `mem.search`.
+
+## Tools
+
+| Tool | What it does |
+|------|-------------|
+| `mem.search` | Search knowledge from all your tools. Supports label and date filters. |
+| `mem.save` | Save a decision, insight, or preference so any tool can find it. |
+| `mem.context` | Read today's Working Memory — focus areas, priorities, recent activity. |
+| `mem.connections` | Explore how a piece of knowledge relates to others across tools and time. |
+| `mem.timeline` | Recent activity grouped by day. |
+| `mem.forget` | Delete a memory by ID. |
+| `mem.threads` | Search past conversations from any tool. |
+| `mem.thread` | Fetch full messages from a conversation with pagination. |
+| `mem.status` | Connection and configuration diagnostics. |
+
+All tools work as Bub comma commands too: `,mem.search query=...`
+
+**Bundled skill:** The `nowledge-mem` skill teaches the agent when and how to use these tools effectively.
+
+## Configuration
+
+No config needed for local use. The plugin reads `~/.nowledge-mem/config.json` and environment variables automatically.
+
+| Variable | Default | What it does |
+|----------|---------|-------------|
+| `NMEM_SESSION_CONTEXT` | `false` | Inject Working Memory + recalled knowledge each turn |
+| `NMEM_SESSION_DIGEST` | `true` | Feed Bub conversations into Mem for other tools to find |
+| `NMEM_API_URL` | *(local)* | Remote Nowledge Mem server URL |
+| `NMEM_API_KEY` | *(none)* | API key for remote access |
+
+### Remote Access
+
+```json
+// ~/.nowledge-mem/config.json
+{
+  "apiUrl": "https://your-server:14242",
+  "apiKey": "your-key"
+}
+```
+
+Or use environment variables (`NMEM_API_URL`, `NMEM_API_KEY`), which override the config file.
+
+## Two Modes
+
+| Mode | Config | What happens |
+|------|--------|-------------|
+| **Default** | nothing | The agent searches and saves on demand. Conversations flow into Mem for other tools to find. |
+| **Session context** | `NMEM_SESSION_CONTEXT=1` | Working Memory and relevant knowledge injected automatically each turn. |
+
+Most users should start with the default.
+
+## Troubleshooting
+
+**nmem not found:** Install with `pip install nmem-cli` or `pipx install nmem-cli`.
+
+**Plugin not loading:** Run `uv run bub hooks` and check that `nowledge_mem` appears in the hook list.
+
+**Server not running:** Start the Nowledge Mem desktop app, or run `nmem status` for diagnostics.
+
+## Links
+
+- [Documentation](https://mem.nowledge.co/docs/integrations/bub)
+- [Discord](https://nowled.ge/discord)
+- [GitHub](https://github.com/nowledge-co/community/tree/main/nowledge-mem-bub-plugin)
+
+---
+
+Made with care by [Nowledge Labs](https://nowledge-labs.ai)

nowledge_mem_bub-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "nowledge-mem-bub"
+version = "0.1.0"
+description = "Nowledge Mem plugin for Bub — cross-ai context for your agent."
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.12"
+authors = [{ name = "Nowledge Labs", email = "hello@nowledge-labs.ai" }]
+keywords = ["bub", "nowledge-mem", "memory", "agent", "knowledge-graph"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = ["bub>=0.3.0a1"]
+
+[project.entry-points."bub"]
+nowledge_mem = "nowledge_mem_bub:plugin"
+
+[project.urls]
+Homepage = "https://mem.nowledge.co"
+Documentation = "https://mem.nowledge.co/docs/integrations/bub"
+Repository = "https://github.com/nowledge-co/community/tree/main/nowledge-mem-bub-plugin"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/nowledge_mem_bub", "src/bub_skills"]

nowledge_mem_bub-0.1.0/src/bub_skills/nowledge-mem/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: nowledge-mem
+description: Search, save, and manage knowledge across all your AI tools through Nowledge Mem.
+license: Apache-2.0
+compatibility: ">=3.12"
+metadata: {}
+allowed-tools:
+  - mem.search
+  - mem.save
+  - mem.context
+  - mem.connections
+  - mem.timeline
+  - mem.forget
+  - mem.threads
+  - mem.thread
+  - mem.status
+---
+
+# Nowledge Mem — Cross-Tool Knowledge for Bub
+
+You have access to the user's personal knowledge graph through Nowledge Mem.
+This graph contains knowledge from all their AI tools — decisions from Claude Code,
+preferences from Cursor, insights from ChatGPT, and more — not just this Bub session.
+Knowledge you save here will be available in their other tools too.
+
+## When to search
+
+Recognise these signals and call `mem.search` **before** answering:
+
+- **Continuity** — the user references something from a previous session or another tool
+- **Decision recall** — "what did we decide about…", "why did we choose…"
+- **Pattern match** — the current topic overlaps with past work in any tool
+- **Implicit recall** — the user assumes you know something you haven't seen this session
+
+Search both memories and threads.  When a memory has `source_thread_id`,
+fetch the full conversation with `mem.thread` for deeper context.
+
+## When to save
+
+Call `mem.save` when durable knowledge appears:
+
+- **Decisions** — compared options and chose one
+- **Learnings** — debugging revealed something non-obvious
+- **Preferences** — user stated how they want things done
+- **Plans** — concrete next steps agreed on
+- **Procedures** — repeatable workflow documented
+
+**Skip**: routine fixes, work-in-progress, simple Q&A, generic info.
+
+Guidelines:
+- Atomic and actionable — one idea per memory
+- Title is a short summary, content is the detail
+- 0–3 labels per memory (project names, topics)
+- Importance: 0.8–1.0 critical | 0.5–0.7 useful | 0.1–0.4 minor
+- Ask before saving: "This seems worth remembering — save it?"
+
+## Working Memory
+
+`mem.context` returns today's Working Memory briefing: focus areas, priorities,
+recent changes, and open questions.  Read it at the start of a session or when
+the user asks "what am I working on?"
+
+## Thread retrieval
+
+Two paths into past conversations:
+
+1. **From a memory**: `mem.search` returns `source_thread_id` → `mem.thread`
+2. **Direct search**: `mem.threads` finds conversations by keyword → `mem.thread`
+
+Use `offset` for pagination on long threads.
+
+## Graph exploration
+
+`mem.connections` shows how a memory relates to other knowledge:
+related topics, EVOLVES chains (how understanding changed over time),
+and source document provenance.
+
+`mem.timeline` shows recent activity grouped by day.

nowledge_mem_bub-0.1.0/src/nowledge_mem_bub/__init__.py

@@ -0,0 +1,6 @@
+"""Nowledge Mem plugin for Bub — cross-tool knowledge for your agent."""
+
+from . import tools as _tools  # noqa: F401 — registers tools in bub.tools.REGISTRY
+from .plugin import plugin
+
+__all__ = ["plugin"]

nowledge_mem_bub-0.1.0/src/nowledge_mem_bub/client.py

@@ -0,0 +1,304 @@
+"""Async wrapper around the nmem CLI.
+
+All memory operations route through ``nmem`` so that Access Anywhere
+(remote config via ``~/.nowledge-mem/config.json`` or ``NMEM_API_URL``)
+works transparently.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import shutil
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+class NmemError(Exception):
+    """Error from nmem CLI execution."""
+
+
+class NmemClient:
+    """Async subprocess wrapper for the ``nmem`` CLI."""
+
+    def __init__(self) -> None:
+        self._cmd: str | None = None
+        self._api_url: str | None = None
+        self._api_key: str | None = None
+        self._load_config()
+
+    # ------------------------------------------------------------------
+    # Config
+    # ------------------------------------------------------------------
+
+    def _load_config(self) -> None:
+        """Load config.  Priority: env vars > config file > defaults."""
+        file_config: dict = {}
+        config_path = Path.home() / ".nowledge-mem" / "config.json"
+        if config_path.is_file():
+            try:
+                file_config = json.loads(config_path.read_text(encoding="utf-8"))
+            except Exception:
+                logger.warning("failed to parse %s", config_path)
+
+        self._api_url = (
+            os.environ.get("NMEM_API_URL")
+            or file_config.get("apiUrl")
+            or file_config.get("api_url")
+            or None
+        )
+        self._api_key = (
+            os.environ.get("NMEM_API_KEY")
+            or file_config.get("apiKey")
+            or file_config.get("api_key")
+            or None
+        )
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _resolve_cmd(self) -> str:
+        if self._cmd is not None:
+            return self._cmd
+        cmd = shutil.which("nmem")
+        if cmd:
+            self._cmd = cmd
+            return cmd
+        raise NmemError(
+            "nmem not found in PATH. Install with: pip install nmem-cli"
+        )
+
+    def _build_env(self) -> dict[str, str]:
+        env = dict(os.environ)
+        if self._api_key:
+            env["NMEM_API_KEY"] = self._api_key
+        return env
+
+    def _base_args(self, *, json_output: bool = True) -> list[str]:
+        args = [self._resolve_cmd()]
+        if json_output:
+            args.append("--json")
+        if self._api_url:
+            args.extend(["--api-url", self._api_url])
+        return args
+
+    def is_available(self) -> bool:
+        return shutil.which("nmem") is not None
+
+    async def _exec(
+        self,
+        *args: str,
+        json_output: bool = True,
+        timeout: float = 15,
+    ) -> str:
+        cmd = [*self._base_args(json_output=json_output), *args]
+        try:
+            proc = await asyncio.create_subprocess_exec(
+                *cmd,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                env=self._build_env(),
+            )
+            stdout, stderr = await asyncio.wait_for(
+                proc.communicate(), timeout=timeout
+            )
+        except asyncio.TimeoutError:
+            proc.kill()  # type: ignore[union-attr]
+            raise NmemError(f"nmem timed out after {timeout}s")
+        except FileNotFoundError:
+            raise NmemError("nmem not found in PATH")
+
+        if proc.returncode != 0:
+            err = stderr.decode(errors="replace").strip()
+            raise NmemError(f"nmem exited {proc.returncode}: {err}")
+
+        return stdout.decode(errors="replace").strip()
+
+    async def _exec_json(self, *args: str, timeout: float = 15) -> dict | list:
+        raw = await self._exec(*args, json_output=True, timeout=timeout)
+        if not raw:
+            return {}
+        try:
+            return json.loads(raw)
+        except json.JSONDecodeError as e:
+            raise NmemError(f"invalid JSON from nmem: {e}")
+
+    # ------------------------------------------------------------------
+    # Memory operations
+    # ------------------------------------------------------------------
+
+    async def search(
+        self,
+        query: str,
+        limit: int = 5,
+        *,
+        labels: list[str] | None = None,
+        importance: float | None = None,
+        event_from: str | None = None,
+        event_to: str | None = None,
+        mode: str | None = None,
+    ) -> list:
+        args = ["m", "search", query, "-n", str(limit)]
+        if importance is not None:
+            args.extend(["--importance", str(importance)])
+        for label in labels or []:
+            args.extend(["-l", label])
+        if event_from:
+            args.extend(["--event-from", event_from])
+        if event_to:
+            args.extend(["--event-to", event_to])
+        if mode:
+            args.extend(["--mode", mode])
+        result = await self._exec_json(*args)
+        if isinstance(result, list):
+            return result
+        return result.get("results", result.get("memories", []))
+
+    async def add_memory(
+        self,
+        content: str,
+        *,
+        title: str | None = None,
+        importance: float | None = None,
+        labels: list[str] | None = None,
+        unit_type: str | None = None,
+        event_start: str | None = None,
+        event_end: str | None = None,
+        temporal_context: str | None = None,
+    ) -> dict:
+        args = ["m", "add", content]
+        if title:
+            args.extend(["-t", title])
+        if importance is not None:
+            args.extend(["-i", str(importance)])
+        for label in labels or []:
+            args.extend(["-l", label])
+        if unit_type:
+            args.extend(["--unit-type", unit_type])
+        if event_start:
+            args.extend(["--event-start", event_start])
+        if event_end:
+            args.extend(["--event-end", event_end])
+        if temporal_context:
+            args.extend(["--temporal-context", temporal_context])
+        args.extend(["-s", "bub"])
+        result = await self._exec_json(*args)
+        return result if isinstance(result, dict) else {}
+
+    async def delete_memory(self, memory_id: str) -> dict:
+        result = await self._exec_json("m", "delete", memory_id, "-f")
+        return result if isinstance(result, dict) else {}
+
+    async def get_memory(self, memory_id: str) -> dict:
+        result = await self._exec_json("m", "show", memory_id)
+        return result if isinstance(result, dict) else {}
+
+    # ------------------------------------------------------------------
+    # Working Memory
+    # ------------------------------------------------------------------
+
+    async def read_working_memory(self) -> dict:
+        try:
+            result = await self._exec_json("wm", "read")
+            return result if isinstance(result, dict) else {"content": ""}
+        except NmemError:
+            wm_path = Path.home() / "ai-now" / "memory.md"
+            if wm_path.is_file():
+                return {
+                    "content": wm_path.read_text(encoding="utf-8"),
+                    "available": True,
+                }
+            return {"content": "", "available": False}
+
+    # ------------------------------------------------------------------
+    # Graph
+    # ------------------------------------------------------------------
+
+    async def graph_expand(
+        self, memory_id: str, depth: int = 1, limit: int = 20
+    ) -> dict:
+        result = await self._exec_json(
+            "g", "expand", memory_id, "--depth", str(depth), "-n", str(limit)
+        )
+        return result if isinstance(result, dict) else {}
+
+    async def graph_evolves(self, memory_id: str, limit: int = 10) -> dict:
+        result = await self._exec_json(
+            "g", "evolves", memory_id, "-n", str(limit)
+        )
+        return result if isinstance(result, dict) else {}
+
+    # ------------------------------------------------------------------
+    # Feed
+    # ------------------------------------------------------------------
+
+    async def feed_events(
+        self,
+        days: int = 7,
+        *,
+        event_type: str | None = None,
+        date_from: str | None = None,
+        date_to: str | None = None,
+    ) -> list:
+        args = ["f", "--last-n-days", str(days)]
+        if event_type:
+            args.extend(["--type", event_type])
+        if date_from:
+            args.extend(["--date-from", date_from])
+        if date_to:
+            args.extend(["--date-to", date_to])
+        result = await self._exec_json(*args)
+        if isinstance(result, list):
+            return result
+        return result.get("events", []) if isinstance(result, dict) else []
+
+    # ------------------------------------------------------------------
+    # Threads
+    # ------------------------------------------------------------------
+
+    async def search_threads(
+        self, query: str, limit: int = 5, source: str | None = None
+    ) -> list:
+        args = ["t", "search", query, "--limit", str(limit)]
+        if source:
+            args.extend(["--source", source])
+        result = await self._exec_json(*args)
+        if isinstance(result, list):
+            return result
+        return result.get("threads", []) if isinstance(result, dict) else []
+
+    async def fetch_thread(
+        self, thread_id: str, limit: int = 20, offset: int = 0
+    ) -> dict:
+        args = ["t", "show", thread_id, "-m", str(limit)]
+        if offset > 0:
+            args.extend(["--offset", str(offset)])
+        args.extend(["--content-limit", "1200"])
+        result = await self._exec_json(*args)
+        return result if isinstance(result, dict) else {}
+
+    async def create_thread(
+        self, thread_id: str, title: str, messages_json: str
+    ) -> dict:
+        result = await self._exec_json(
+            "t", "create", "--id", thread_id, "-t", title,
+            "-m", messages_json, "-s", "bub",
+        )
+        return result if isinstance(result, dict) else {}
+
+    async def append_thread(self, thread_id: str, messages_json: str) -> dict:
+        result = await self._exec_json(
+            "t", "append", thread_id, "-m", messages_json,
+        )
+        return result if isinstance(result, dict) else {}
+
+    # ------------------------------------------------------------------
+    # Status
+    # ------------------------------------------------------------------
+
+    async def status(self) -> str:
+        return await self._exec("status", json_output=False)

nowledge_mem_bub-0.1.0/src/nowledge_mem_bub/plugin.py

@@ -0,0 +1,190 @@
+"""Bub hook implementations for Nowledge Mem.
+
+Hooks:
+  system_prompt  — behavioural guidance (~50 tokens) + optional WM / recall
+  load_state     — fetch Working Memory and (if session_context) recalled memories
+  save_state     — capture each turn to a Nowledge Mem thread (incremental)
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import os
+
+from bub import hookimpl
+from bub.envelope import content_of
+
+from .client import NmemClient, NmemError
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Behavioural guidance injected into the system prompt.
+# Cost: ~50 tokens.  Adjusts when session_context is on to avoid redundant
+# tool calls for context that was already injected.
+# ---------------------------------------------------------------------------
+
+_GUIDANCE_BASE = """\
+You have access to the user's personal knowledge graph (Nowledge Mem).
+It contains knowledge from all their tools — Claude Code, Cursor, ChatGPT, and others — not just this session.
+When prior context would improve your response, search with mem.search.
+When the conversation produces something worth keeping, save it with mem.save.
+When a memory has source_thread_id, fetch the full conversation with mem.thread."""
+
+_GUIDANCE_WITH_CONTEXT = """\
+You have access to the user's personal knowledge graph (Nowledge Mem).
+It contains knowledge from all their tools — not just this session.
+Relevant memories and Working Memory have already been injected into context.
+Use mem.search only for specific follow-ups beyond what was auto-recalled.
+When the conversation produces something worth keeping, save it with mem.save."""
+
+
+class NowledgeMemPlugin:
+    """Nowledge Mem integration for Bub.
+
+    Configuration (env vars):
+      NMEM_SESSION_CONTEXT  — "1"/"true"  to inject WM + recall each turn
+      NMEM_SESSION_DIGEST   — "0"/"false" to disable thread capture
+      NMEM_API_URL          — remote server URL
+      NMEM_API_KEY          — API key (passed to nmem via env, never logged)
+    """
+
+    def __init__(self) -> None:
+        self.client = NmemClient()
+        self._session_context = os.environ.get(
+            "NMEM_SESSION_CONTEXT", ""
+        ).lower() in ("1", "true", "yes")
+        self._session_digest = os.environ.get(
+            "NMEM_SESSION_DIGEST", "1"
+        ).lower() not in ("0", "false", "no")
+
+    # ------------------------------------------------------------------
+    # system_prompt — sync, call_many, results joined with \n\n
+    # ------------------------------------------------------------------
+
+    @hookimpl
+    def system_prompt(self, prompt, state) -> str:
+        """Inject behavioural guidance and, when session_context is on,
+        Working Memory + recalled knowledge from state."""
+        sections: list[str] = []
+
+        # Always: behavioural nudge
+        if self._session_context:
+            sections.append(_GUIDANCE_WITH_CONTEXT)
+        else:
+            sections.append(_GUIDANCE_BASE)
+
+        if not self._session_context:
+            return "\n".join(sections)
+
+        # Session context mode: include WM + recalled memories
+        wm = state.get("_nmem_working_memory")
+        if wm:
+            sections.append(f"<working-memory>\n{wm}\n</working-memory>")
+
+        recalled = state.get("_nmem_recalled")
+        if recalled:
+            lines: list[str] = []
+            for r in recalled:
+                title = r.get("title", "")
+                text = r.get("content", "")[:300]
+                mid = r.get("id", "")
+                thread = r.get("source_thread_id", "")
+                entry = f"- [{title}] {text}"
+                if mid:
+                    entry += f" (id: {mid})"
+                if thread:
+                    entry += f" (thread: {thread})"
+                lines.append(entry)
+            sections.append(
+                "<recalled-knowledge>\n"
+                + "\n".join(lines)
+                + "\n</recalled-knowledge>"
+            )
+
+        return "\n\n".join(sections)
+
+    # ------------------------------------------------------------------
+    # load_state — async, call_many, dicts merged into state
+    # ------------------------------------------------------------------
+
+    @hookimpl
+    async def load_state(self, message, session_id) -> dict:
+        """Load Working Memory and recalled memories (when session_context is on)."""
+        state: dict = {"_nmem_client": self.client}
+
+        if not self.client.is_available():
+            logger.debug("nmem not in PATH, skipping load_state")
+            return state
+
+        if not self._session_context:
+            # Default mode: no per-turn fetches.  The agent calls
+            # mem.context or mem.search on demand.
+            return state
+
+        # Session context mode: fetch WM + recalled memories
+        try:
+            wm = await self.client.read_working_memory()
+            content = wm.get("content", "")
+            if content:
+                state["_nmem_working_memory"] = content
+        except Exception as exc:
+            logger.debug("working memory read failed: %s", exc)
+
+        # Recall: search for memories relevant to the current message
+        query = content_of(message)
+        if query and len(query.strip()) > 3:
+            try:
+                results = await self.client.search(query[:500], limit=5)
+                if results:
+                    state["_nmem_recalled"] = results
+            except Exception as exc:
+                logger.debug("recall search failed: %s", exc)
+
+        return state
+
+    # ------------------------------------------------------------------
+    # save_state — async, call_many, always runs (finally block)
+    # ------------------------------------------------------------------
+
+    @hookimpl
+    async def save_state(self, session_id, state, message, model_output) -> None:
+        """Append the turn (user + assistant) to a Nowledge Mem thread."""
+        if not self._session_digest:
+            return
+        if not self.client.is_available():
+            return
+
+        try:
+            user_content = content_of(message)
+            if not user_content or not model_output:
+                return
+
+            digest = hashlib.sha1(session_id.encode()).hexdigest()[:10]
+            thread_id = f"bub-{digest}"
+
+            messages = [
+                {"role": "user", "content": user_content[:800]},
+                {"role": "assistant", "content": str(model_output)[:800]},
+            ]
+            messages_json = json.dumps(messages)
+
+            try:
+                await self.client.append_thread(thread_id, messages_json)
+            except NmemError:
+                # Thread doesn't exist yet — create it
+                title = f"Bub Session ({session_id[:30]})"
+                try:
+                    await self.client.create_thread(
+                        thread_id, title, messages_json
+                    )
+                except Exception as exc:
+                    logger.debug("thread create failed: %s", exc)
+        except Exception as exc:
+            # save_state must never raise — it runs in a finally block
+            logger.debug("session capture failed: %s", exc)
+
+
+plugin = NowledgeMemPlugin()

nowledge_mem_bub-0.1.0/src/nowledge_mem_bub/tools.py

@@ -0,0 +1,376 @@
+"""Nowledge Mem tools for Bub agents.
+
+Tools are registered in ``bub.tools.REGISTRY`` on import via the ``@tool``
+decorator.  The plugin's ``__init__.py`` imports this module to trigger
+registration.
+
+Naming follows Bub conventions: ``mem.*`` namespace, dot-separated.
+In the model's tool list dots become underscores (``mem_search``, etc.).
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from bub import tool
+
+from .client import NmemClient, NmemError
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _get_client(context: Any) -> NmemClient:
+    """Retrieve NmemClient from tool context state, or create a fresh one."""
+    client = context.state.get("_nmem_client")
+    if client is None:
+        client = NmemClient()
+    return client
+
+
+def _fmt_memory(m: dict) -> str:
+    """Format one memory result for the agent."""
+    mid = m.get("id", "")
+    title = m.get("title", "")
+    text = m.get("content", "")
+    score = m.get("score", "")
+    labels = m.get("labels", [])
+    thread = m.get("source_thread_id", "")
+    parts = [f"[{title}]" if title else "", text[:400]]
+    if score:
+        parts.append(f"score: {score}")
+    if labels:
+        parts.append(f"labels: {', '.join(labels)}")
+    if mid:
+        parts.append(f"id: {mid}")
+    if thread:
+        parts.append(f"thread: {thread}")
+    return " · ".join(p for p in parts if p)
+
+
+# ---------------------------------------------------------------------------
+# mem.search
+# ---------------------------------------------------------------------------
+
+
+class MemSearchInput(BaseModel):
+    query: str = Field(..., description="Search query.")
+    limit: int = Field(5, description="Max results (1–20).")
+    labels: list[str] = Field(
+        default_factory=list, description="Filter by labels."
+    )
+    event_from: str | None = Field(
+        None, description="Event start date filter (ISO, e.g. 2025-01)."
+    )
+    event_to: str | None = Field(
+        None, description="Event end date filter (ISO)."
+    )
+
+
+@tool(context=True, name="mem.search", model=MemSearchInput)
+async def mem_search(param: MemSearchInput, *, context: Any) -> str:
+    """Search your personal knowledge graph.  Returns memories ranked by relevance.  Use when prior context would help."""
+    client = _get_client(context)
+    results = await client.search(
+        param.query,
+        limit=param.limit,
+        labels=param.labels or None,
+        event_from=param.event_from,
+        event_to=param.event_to,
+    )
+    if not results:
+        return "(no matches)"
+    lines = [_fmt_memory(r) for r in results]
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# mem.save
+# ---------------------------------------------------------------------------
+
+
+class MemSaveInput(BaseModel):
+    content: str = Field(..., description="Memory content to save.")
+    title: str | None = Field(None, description="Short descriptive title.")
+    importance: float = Field(
+        0.7, description="Importance 0.0–1.0. 0.8+ critical, 0.5–0.7 useful."
+    )
+    labels: list[str] = Field(
+        default_factory=list, description="Topic labels (0–3 recommended)."
+    )
+    unit_type: str = Field(
+        "fact",
+        description="Type: fact, decision, learning, preference, plan, procedure, context, event.",
+    )
+    event_start: str | None = Field(
+        None, description="When it happened (ISO date)."
+    )
+    event_end: str | None = Field(
+        None, description="End date if range (ISO)."
+    )
+    temporal_context: str = Field(
+        "present", description="past, present, future, or timeless."
+    )
+
+
+@tool(context=True, name="mem.save", model=MemSaveInput)
+async def mem_save(param: MemSaveInput, *, context: Any) -> str:
+    """Save a memory (decision, insight, preference, plan, …) to your knowledge graph.  Check for duplicates before saving."""
+    client = _get_client(context)
+
+    # Pre-save dedup: search for high-similarity existing memory
+    try:
+        check_query = param.title or param.content[:200]
+        existing = await client.search(check_query, limit=3)
+        for r in existing:
+            score = r.get("score", 0)
+            if isinstance(score, (int, float)) and score >= 0.9:
+                mid = r.get("id", "unknown")
+                title = r.get("title", "")
+                return (
+                    f"(duplicate detected — existing memory: [{title}] id: {mid})"
+                )
+    except Exception:
+        pass  # dedup is best-effort
+
+    result = await client.add_memory(
+        param.content,
+        title=param.title,
+        importance=param.importance,
+        labels=param.labels or None,
+        unit_type=param.unit_type,
+        event_start=param.event_start,
+        event_end=param.event_end,
+        temporal_context=param.temporal_context,
+    )
+    mid = result.get("id", "")
+    title = param.title or param.content[:40]
+    label_str = ", ".join(param.labels) if param.labels else ""
+    parts = [f"Saved: {title} [{param.unit_type}]"]
+    if mid:
+        parts.append(f"id: {mid}")
+    if label_str:
+        parts.append(f"labels: {label_str}")
+    return " · ".join(parts)
+
+
+# ---------------------------------------------------------------------------
+# mem.context — Working Memory
+# ---------------------------------------------------------------------------
+
+
+@tool(context=True, name="mem.context")
+async def mem_context(*, context: Any) -> str:
+    """Read today's Working Memory briefing: focus areas, priorities, recent activity."""
+    # Check if already loaded in state
+    wm = context.state.get("_nmem_working_memory")
+    if wm:
+        return wm
+
+    client = _get_client(context)
+    result = await client.read_working_memory()
+    content = result.get("content", "")
+    return content or "(no Working Memory available)"
+
+
+# ---------------------------------------------------------------------------
+# mem.connections — graph exploration
+# ---------------------------------------------------------------------------
+
+
+class MemConnectionsInput(BaseModel):
+    memory_id: str | None = Field(
+        None, description="Memory ID to explore.  If omitted, searches by query."
+    )
+    query: str | None = Field(
+        None,
+        description="Search query (used when memory_id is not provided).",
+    )
+
+
+@tool(context=True, name="mem.connections", model=MemConnectionsInput)
+async def mem_connections(param: MemConnectionsInput, *, context: Any) -> str:
+    """Explore how a memory connects to other knowledge: related topics, version chains (EVOLVES), source documents."""
+    client = _get_client(context)
+
+    mid = param.memory_id
+    if not mid:
+        if not param.query:
+            return "(provide memory_id or query)"
+        results = await client.search(param.query, limit=1)
+        if not results:
+            return "(no matching memory found)"
+        mid = results[0].get("id", "")
+        if not mid:
+            return "(no memory ID in result)"
+
+    sections: list[str] = []
+
+    # Neighbours
+    try:
+        expand = await client.graph_expand(mid)
+        nodes = expand.get("nodes", expand.get("neighbors", []))
+        if nodes:
+            lines = []
+            for n in nodes[:15]:
+                label = n.get("label", n.get("title", ""))
+                nid = n.get("id", "")
+                edge = n.get("edge_type", n.get("relationship", ""))
+                lines.append(f"  - {label} ({edge}) id: {nid}")
+            sections.append("Connections:\n" + "\n".join(lines))
+    except Exception as exc:
+        logger.debug("graph expand failed: %s", exc)
+
+    # EVOLVES chain
+    try:
+        evolves = await client.graph_evolves(mid)
+        chain = evolves.get("chain", evolves.get("evolves", []))
+        if chain:
+            lines = []
+            for e in chain[:10]:
+                title = e.get("title", "")
+                eid = e.get("id", "")
+                rel = e.get("relationship", e.get("type", ""))
+                lines.append(f"  - {title} ({rel}) id: {eid}")
+            sections.append("Evolution:\n" + "\n".join(lines))
+    except Exception as exc:
+        logger.debug("graph evolves failed: %s", exc)
+
+    return "\n\n".join(sections) if sections else "(no connections found)"
+
+
+# ---------------------------------------------------------------------------
+# mem.timeline — activity feed
+# ---------------------------------------------------------------------------
+
+
+class MemTimelineInput(BaseModel):
+    last_n_days: int = Field(7, description="Number of recent days (1–90).")
+    date_from: str | None = Field(None, description="Start date (ISO).")
+    date_to: str | None = Field(None, description="End date (ISO).")
+
+
+@tool(context=True, name="mem.timeline", model=MemTimelineInput)
+async def mem_timeline(param: MemTimelineInput, *, context: Any) -> str:
+    """Show recent activity: memories created, conversations captured, insights generated.  Grouped by day."""
+    client = _get_client(context)
+    events = await client.feed_events(
+        days=param.last_n_days,
+        date_from=param.date_from,
+        date_to=param.date_to,
+    )
+    if not events:
+        return "(no recent activity)"
+
+    lines: list[str] = []
+    current_date = ""
+    for ev in events[:50]:
+        date = ev.get("date", ev.get("created_at", ""))[:10]
+        if date != current_date:
+            current_date = date
+            lines.append(f"\n## {date}")
+        etype = ev.get("type", ev.get("event_type", ""))
+        title = ev.get("title", ev.get("summary", ""))
+        mid = ev.get("memory_id", "")
+        entry = f"- {etype}: {title}"
+        if mid:
+            entry += f" (id: {mid})"
+        lines.append(entry)
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# mem.forget
+# ---------------------------------------------------------------------------
+
+
+@tool(context=True, name="mem.forget")
+async def mem_forget(memory_id: str, *, context: Any) -> str:
+    """Delete a memory by ID."""
+    client = _get_client(context)
+    await client.delete_memory(memory_id)
+    return f"deleted: {memory_id}"
+
+
+# ---------------------------------------------------------------------------
+# mem.threads — search past conversations
+# ---------------------------------------------------------------------------
+
+
+@tool(context=True, name="mem.threads")
+async def mem_thread_search(
+    query: str, limit: int = 5, *, context: Any
+) -> str:
+    """Search past conversations by keyword.  Returns threads with matched message snippets."""
+    client = _get_client(context)
+    threads = await client.search_threads(query, limit=limit)
+    if not threads:
+        return "(no matching threads)"
+    lines: list[str] = []
+    for t in threads:
+        tid = t.get("id", t.get("thread_id", ""))
+        title = t.get("title", "")
+        msgs = t.get("message_count", t.get("total_messages", ""))
+        snippet = t.get("snippet", t.get("matched_text", ""))[:200]
+        entry = f"- [{title}] ({msgs} messages) id: {tid}"
+        if snippet:
+            entry += f"\n  {snippet}"
+        lines.append(entry)
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# mem.thread — fetch full conversation
+# ---------------------------------------------------------------------------
+
+
+@tool(context=True, name="mem.thread")
+async def mem_thread_fetch(
+    thread_id: str,
+    offset: int = 0,
+    limit: int = 20,
+    *,
+    context: Any,
+) -> str:
+    """Fetch messages from a specific thread (conversation).  Supports pagination."""
+    client = _get_client(context)
+    result = await client.fetch_thread(thread_id, limit=limit, offset=offset)
+
+    title = result.get("title", "")
+    total = result.get("total_messages", result.get("message_count", "?"))
+    messages = result.get("messages", [])
+    has_more = result.get("has_more", len(messages) >= limit)
+
+    lines = [f"Thread: {title} ({total} messages)"]
+    for msg in messages:
+        role = msg.get("role", "")
+        text = msg.get("content", "")[:600]
+        lines.append(f"[{role}] {text}")
+
+    if has_more:
+        next_offset = offset + len(messages)
+        lines.append(f"\n(more messages available — use offset={next_offset})")
+
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# mem.status — diagnostics
+# ---------------------------------------------------------------------------
+
+
+@tool(context=True, name="mem.status")
+async def mem_status(*, context: Any) -> str:
+    """Check Nowledge Mem connection status and configuration."""
+    client = _get_client(context)
+    try:
+        return await client.status()
+    except NmemError as exc:
+        return f"(connection failed: {exc})"