Skip to content

Commit d486fc4

Browse files
wey-guwey-gu
authored
Merge pull request #114 from nowledge-co/dev_0610
feat: add Bub plugin — cross-tool knowledge for Bub agents
2 parents 41e1168 + e06f989 commit d486fc4

10 files changed

Lines changed: 1103 additions & 0 deletions

File tree

‎nowledge-mem-bub-plugin/.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
__pycache__/
2+
3+
dist

‎nowledge-mem-bub-plugin/CHANGELOG.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Changelog
2+
3+
## 0.1.1 (2026-03-12)
4+
5+
- Fixed: broad `NmemError` catch in `save_state` no longer causes double timeout (up to 30s) when nmem is unreachable — only retries on "not found" errors, and caches thread existence after first success
6+
- Fixed: `bub_skills` package now includes `__init__.py` so bub can discover the bundled skill via `importlib`
7+
- Removed: unused `get_memory` method from client
8+
9+
## 0.1.0 (2026-03-12)
10+
11+
Initial release — brings cross-tool knowledge into Bub.
12+
13+
- 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
14+
- Hook-based integration: behavioural guidance via `system_prompt`, optional Working Memory injection via `load_state`, incremental thread capture via `save_state`
15+
- Two modes: default (agent-driven, on-demand) and session context (auto-inject Working Memory + recalled knowledge each turn)
16+
- Conversations in Bub flow into Nowledge Mem so other tools can find them
17+
- Pre-save deduplication check
18+
- Bundled `nowledge-mem` skill for agent self-guidance
19+
- Access Anywhere support via `~/.nowledge-mem/config.json` or `NMEM_API_URL` / `NMEM_API_KEY`

‎nowledge-mem-bub-plugin/README.md‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
# Nowledge Mem — Bub Plugin
2+
3+
> Bring your cross-tool knowledge into Bub, and share what you learn in Bub with every other tool.
4+
5+
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.
6+
7+
## Install
8+
9+
```bash
10+
pip install nowledge-mem-bub
11+
```
12+
13+
**Prerequisite:** `nmem` CLI must be in your PATH:
14+
15+
```bash
16+
pip install nmem-cli # or: pipx install nmem-cli
17+
nmem status # verify connection
18+
```
19+
20+
## Verify
21+
22+
```bash
23+
uv run bub hooks # should list nowledge_mem for system_prompt, load_state, save_state
24+
uv run bub run "what was I working on this week?"
25+
```
26+
27+
If you have existing knowledge in Nowledge Mem, the agent should find it through `mem.search`.
28+
29+
## Tools
30+
31+
| Tool | What it does |
32+
|------|-------------|
33+
| `mem.search` | Search knowledge from all your tools. Supports label and date filters. |
34+
| `mem.save` | Save a decision, insight, or preference so any tool can find it. |
35+
| `mem.context` | Read today's Working Memory — focus areas, priorities, recent activity. |
36+
| `mem.connections` | Explore how a piece of knowledge relates to others across tools and time. |
37+
| `mem.timeline` | Recent activity grouped by day. |
38+
| `mem.forget` | Delete a memory by ID. |
39+
| `mem.threads` | Search past conversations from any tool. |
40+
| `mem.thread` | Fetch full messages from a conversation with pagination. |
41+
| `mem.status` | Connection and configuration diagnostics. |
42+
43+
All tools work as Bub comma commands too: `,mem.search query=...`
44+
45+
**Bundled skill:** The `nowledge-mem` skill teaches the agent when and how to use these tools effectively.
46+
47+
## Configuration
48+
49+
No config needed for local use. The plugin reads `~/.nowledge-mem/config.json` and environment variables automatically.
50+
51+
| Variable | Default | What it does |
52+
|----------|---------|-------------|
53+
| `NMEM_SESSION_CONTEXT` | `false` | Inject Working Memory + recalled knowledge each turn |
54+
| `NMEM_SESSION_DIGEST` | `true` | Feed Bub conversations into Mem for other tools to find |
55+
| `NMEM_API_URL` | *(local)* | Remote Nowledge Mem server URL |
56+
| `NMEM_API_KEY` | *(none)* | API key for remote access |
57+
58+
### Remote Access
59+
60+
```json
61+
// ~/.nowledge-mem/config.json
62+
{
63+
"apiUrl": "https://your-server:14242",
64+
"apiKey": "your-key"
65+
}
66+
```
67+
68+
Or use environment variables (`NMEM_API_URL`, `NMEM_API_KEY`), which override the config file.
69+
70+
## Two Modes
71+
72+
| Mode | Config | What happens |
73+
|------|--------|-------------|
74+
| **Default** | nothing | The agent searches and saves on demand. Conversations flow into Mem for other tools to find. |
75+
| **Session context** | `NMEM_SESSION_CONTEXT=1` | Working Memory and relevant knowledge injected automatically each turn. |
76+
77+
Most users should start with the default.
78+
79+
## Troubleshooting
80+
81+
**nmem not found:** Install with `pip install nmem-cli` or `pipx install nmem-cli`.
82+
83+
**Plugin not loading:** Run `uv run bub hooks` and check that `nowledge_mem` appears in the hook list.
84+
85+
**Server not running:** Start the Nowledge Mem desktop app, or run `nmem status` for diagnostics.
86+
87+
## Links
88+
89+
- [Documentation](https://mem.nowledge.co/docs/integrations/bub)
90+
- [Discord](https://nowled.ge/discord)
91+
- [GitHub](https://github.com/nowledge-co/community/tree/main/nowledge-mem-bub-plugin)
92+
93+
---
94+
95+
Made with care by [Nowledge Labs](https://nowledge-labs.ai)

‎nowledge-mem-bub-plugin/pyproject.toml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
[project]
2+
name = "nowledge-mem-bub"
3+
version = "0.1.1"
4+
description = "Nowledge Mem plugin for Bub — cross-ai context for your agent."
5+
readme = "README.md"
6+
license = "Apache-2.0"
7+
requires-python = ">=3.12"
8+
authors = [{ name = "Nowledge Labs", email = "hello@nowledge-labs.ai" }]
9+
keywords = ["bub", "nowledge-mem", "memory", "agent", "knowledge-graph"]
10+
classifiers = [
11+
"Development Status :: 3 - Alpha",
12+
"Intended Audience :: Developers",
13+
"Topic :: Scientific/Engineering :: Artificial Intelligence",
14+
]
15+
dependencies = ["bub>=0.3.0a1"]
16+
17+
[project.entry-points."bub"]
18+
nowledge_mem = "nowledge_mem_bub:plugin"
19+
20+
[project.urls]
21+
Homepage = "https://mem.nowledge.co"
22+
Documentation = "https://mem.nowledge.co/docs/integrations/bub"
23+
Repository = "https://github.com/nowledge-co/community/tree/main/nowledge-mem-bub-plugin"
24+
25+
[build-system]
26+
requires = ["hatchling"]
27+
build-backend = "hatchling.build"
28+
29+
[tool.hatch.build.targets.wheel]
30+
packages = ["src/nowledge_mem_bub", "src/bub_skills"]

‎nowledge-mem-bub-plugin/src/bub_skills/__init__.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# Namespace marker — bub discovers skills via importlib __path__.

‎nowledge-mem-bub-plugin/src/bub_skills/nowledge-mem/SKILL.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
---
2+
name: nowledge-mem
3+
description: Search, save, and manage knowledge across all your AI tools through Nowledge Mem.
4+
license: Apache-2.0
5+
compatibility: ">=3.12"
6+
metadata: {}
7+
allowed-tools:
8+
- mem.search
9+
- mem.save
10+
- mem.context
11+
- mem.connections
12+
- mem.timeline
13+
- mem.forget
14+
- mem.threads
15+
- mem.thread
16+
- mem.status
17+
---
18+
19+
# Nowledge Mem — Cross-Tool Knowledge for Bub
20+
21+
You have access to the user's personal knowledge graph through Nowledge Mem.
22+
This graph contains knowledge from all their AI tools — decisions from Claude Code,
23+
preferences from Cursor, insights from ChatGPT, and more — not just this Bub session.
24+
Knowledge you save here will be available in their other tools too.
25+
26+
## When to search
27+
28+
Recognise these signals and call `mem.search` **before** answering:
29+
30+
- **Continuity** — the user references something from a previous session or another tool
31+
- **Decision recall** — "what did we decide about…", "why did we choose…"
32+
- **Pattern match** — the current topic overlaps with past work in any tool
33+
- **Implicit recall** — the user assumes you know something you haven't seen this session
34+
35+
Search both memories and threads. When a memory has `source_thread_id`,
36+
fetch the full conversation with `mem.thread` for deeper context.
37+
38+
## When to save
39+
40+
Call `mem.save` when durable knowledge appears:
41+
42+
- **Decisions** — compared options and chose one
43+
- **Learnings** — debugging revealed something non-obvious
44+
- **Preferences** — user stated how they want things done
45+
- **Plans** — concrete next steps agreed on
46+
- **Procedures** — repeatable workflow documented
47+
48+
**Skip**: routine fixes, work-in-progress, simple Q&A, generic info.
49+
50+
Guidelines:
51+
- Atomic and actionable — one idea per memory
52+
- Title is a short summary, content is the detail
53+
- 0–3 labels per memory (project names, topics)
54+
- Importance: 0.8–1.0 critical | 0.5–0.7 useful | 0.1–0.4 minor
55+
- Ask before saving: "This seems worth remembering — save it?"
56+
57+
## Working Memory
58+
59+
`mem.context` returns today's Working Memory briefing: focus areas, priorities,
60+
recent changes, and open questions. Read it at the start of a session or when
61+
the user asks "what am I working on?"
62+
63+
## Thread retrieval
64+
65+
Two paths into past conversations:
66+
67+
1. **From a memory**: `mem.search` returns `source_thread_id` → `mem.thread`
68+
2. **Direct search**: `mem.threads` finds conversations by keyword → `mem.thread`
69+
70+
Use `offset` for pagination on long threads.
71+
72+
## Graph exploration
73+
74+
`mem.connections` shows how a memory relates to other knowledge:
75+
related topics, EVOLVES chains (how understanding changed over time),
76+
and source document provenance.
77+
78+
`mem.timeline` shows recent activity grouped by day.

‎nowledge-mem-bub-plugin/src/nowledge_mem_bub/__init__.py‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
"""Nowledge Mem plugin for Bub — cross-tool knowledge for your agent."""
2+
3+
from . import tools as _tools # noqa: F401 — registers tools in bub.tools.REGISTRY
4+
from .plugin import plugin
5+
6+
__all__ = ["plugin"]

0 commit comments

Comments
 (0)