Metadata-Version: 2.4
Name: nowledge-mem-bub
Version: 0.7.3
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
# Arch Linux: yay -S nmem-cli  # or: paru -S nmem-cli
nmem status             # verify connection
```

## Verify

```bash
uv run bub hooks        # should list nowledge_mem for system_prompt, build_prompt, 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 Context Bundle — identity, active scope, active rules, and Working Memory. |
| `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.

## Customize without editing the plugin

Bub does not currently expose a dedicated user-owned instruction file through this package.

- Use Bub's own runtime prompt or configuration surface if you need extra behavior guidance.
- Keep connection and lane behavior in shared config or env vars.
- Do not patch the installed Bub plugin files directly.

| Variable | Default | What it does |
|----------|---------|-------------|
| `NMEM_SESSION_CONTEXT` | `false` | Inject Context Bundle + recalled knowledge each turn |
| `NMEM_SESSION_DIGEST` | `true` | Feed Bub conversations into Mem for other tools to find |
| `NMEM_SPACE` | *(unset)* | Ambient space lane for this Bub process |
| `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",
  "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` | Context Bundle and relevant knowledge injected automatically each turn. |

Most users should start with the default.

If one Bub process naturally belongs to one project or agent lane, set `NMEM_SPACE="Research Agent"` before launch. All CLI-backed Context Bundle, search, save, and thread commands will then stay in that lane. Legacy `NMEM_SPACE_ID` still works for older setups.

Bub is process-scoped today: if you run multiple Bub agents that need different memory lanes, give each process its own `NMEM_SPACE` (or keep them on `Default`). Shared spaces, default retrieval, and agent guidance still come from Mem's shared `/spaces` profile.

## 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)
