|
| 1 | +# Nowledge Mem Plugin for Proma |
| 2 | + |
| 3 | +Integrates Nowledge Mem's personal knowledge graph into Proma, providing persistent cross-session memory through MCP tools, lifecycle hooks, and a companion skill. |
| 4 | + |
| 5 | +## Prerequisites |
| 6 | + |
| 7 | +- [Proma](https://proma.ai) desktop app or CLI |
| 8 | +- Nowledge Mem server running (desktop app or remote) |
| 9 | +- Python 3.9+ (for hook scripts) |
| 10 | +- `nmem` CLI in PATH (bundled with [Nowledge Mem desktop app](https://mem.nowledge.co/), or `pip install nmem-cli`) |
| 11 | + |
| 12 | +## Installation |
| 13 | + |
| 14 | +### 1. Configure MCP Server |
| 15 | + |
| 16 | +Add the Nowledge Mem MCP server to your Proma workspace `mcp.json`: |
| 17 | + |
| 18 | +**Path:** `~/.proma/agent-workspaces/default/mcp.json` |
| 19 | + |
| 20 | +```json |
| 21 | +{ |
| 22 | + "servers": { |
| 23 | + "nowledge-mem": { |
| 24 | + "url": "http://127.0.0.1:14242/mcp/", |
| 25 | + "type": "streamableHttp", |
| 26 | + "headers": { |
| 27 | + "APP": "Proma", |
| 28 | + "Authorization": "Bearer <your-nmem-api-key>", |
| 29 | + "X-NMEM-API-Key": "<your-nmem-api-key>" |
| 30 | + } |
| 31 | + } |
| 32 | + } |
| 33 | +} |
| 34 | +``` |
| 35 | + |
| 36 | +For remote Mem setups, replace the URL with your remote server (e.g., `https://mem.example.com/mcp/`). |
| 37 | + |
| 38 | +### 2. Install Hook Scripts |
| 39 | + |
| 40 | +Copy the hook scripts to your Proma hooks directory: |
| 41 | + |
| 42 | +```bash |
| 43 | +mkdir -p ~/.proma/hooks/ |
| 44 | +cp hooks/save-to-nmem.py ~/.proma/hooks/ |
| 45 | +cp hooks/read-working-memory.py ~/.proma/hooks/ |
| 46 | +``` |
| 47 | + |
| 48 | +### 3. Enable Lifecycle Hooks |
| 49 | + |
| 50 | +Merge the hooks configuration from `hooks/hooks.json` into `~/.proma/settings.json`: |
| 51 | + |
| 52 | +```json |
| 53 | +{ |
| 54 | + "hooks": { |
| 55 | + "Stop": [ |
| 56 | + { |
| 57 | + "hooks": [ |
| 58 | + { |
| 59 | + "type": "command", |
| 60 | + "command": "python \"<proma-home>/hooks/save-to-nmem.py\"", |
| 61 | + "timeout": 30, |
| 62 | + "async": true |
| 63 | + } |
| 64 | + ] |
| 65 | + } |
| 66 | + ], |
| 67 | + "SessionStart": [ |
| 68 | + { |
| 69 | + "matcher": "startup|resume", |
| 70 | + "hooks": [ |
| 71 | + { |
| 72 | + "type": "command", |
| 73 | + "command": "python \"<proma-home>/hooks/read-working-memory.py\"", |
| 74 | + "timeout": 10, |
| 75 | + "async": true |
| 76 | + } |
| 77 | + ] |
| 78 | + } |
| 79 | + ] |
| 80 | + } |
| 81 | +} |
| 82 | +``` |
| 83 | + |
| 84 | +Replace `<proma-home>` with your actual Proma home path (usually `~/.proma` on macOS/Linux or `C:\Users\<user>\.proma` on Windows). |
| 85 | + |
| 86 | +### 4. Install the Skill |
| 87 | + |
| 88 | +Copy the nmem skill to your Proma workspace: |
| 89 | + |
| 90 | +```bash |
| 91 | +mkdir -p ~/.proma/agent-workspaces/default/skills/nmem/ |
| 92 | +cp skills/nmem/SKILL.md ~/.proma/agent-workspaces/default/skills/nmem/ |
| 93 | +``` |
| 94 | + |
| 95 | +### 5. (Recommended) Add CLAUDE.md Guidance |
| 96 | + |
| 97 | +Add the following guidance to your CLAUDE.md so Proma knows when to use nmem vs built-in memory: |
| 98 | + |
| 99 | +```markdown |
| 100 | +## Nowledge Mem (nmem) Usage |
| 101 | + |
| 102 | +When nmem MCP tools (`mcp__nowledge-mem__*`) are available: |
| 103 | + |
| 104 | +- **Cross-session persistence** -> nmem (`mcp__nowledge-mem__add_memory`) |
| 105 | +- **Within-session context** -> built-in `mcp__mem__*` |
| 106 | +- **Historical decisions, past discussions** -> `mcp__nowledge-mem__search_memories` |
| 107 | +- **Session archiving** -> `mcp__nowledge-mem__save_thread` |
| 108 | + |
| 109 | +**Proactive behaviors:** |
| 110 | +- Read Working Memory at session start |
| 111 | +- Distill key decisions to nmem Memories |
| 112 | +- When user says "before", "last time": search nmem + built-in memory |
| 113 | +``` |
| 114 | + |
| 115 | +### 6. Restart Proma |
| 116 | + |
| 117 | +Restart Proma for the MCP server and hooks to take effect. Verify with `/nmem-status` in a new session. |
| 118 | + |
| 119 | +## Architecture |
| 120 | + |
| 121 | +``` |
| 122 | +Proma Agent |
| 123 | + | |
| 124 | + |-- mcp.json --> nmem MCP server (tools: search, save, status) |
| 125 | + |-- Stop Hook --> save-to-nmem.py (auto-capture sessions) |
| 126 | + |-- SessionStart Hook --> read-working-memory.py (inject context) |
| 127 | + |-- nmem Skill --> /nmem-save, /nmem-search, /nmem-status |
| 128 | +``` |
| 129 | + |
| 130 | +## How It Works |
| 131 | + |
| 132 | +1. **MCP Tools** — `mcp__nowledge-mem__*` tools are available to the agent for on-demand memory operations: search past decisions, save new learnings, read working memory. |
| 133 | +2. **Stop Hook** — After every agent response, `save-to-nmem.py` parses the current Proma session JSONL (`~/.proma/agent-sessions/<id>.jsonl`) and uploads the messages to nmem's thread store via REST API. |
| 134 | +3. **SessionStart Hook** — On new or resumed sessions, `read-working-memory.py` calls `nmem wm read` and outputs the briefing for context injection. |
| 135 | +4. **Skill** — Slash commands provide manual control as a fallback. |
| 136 | + |
| 137 | +### Session Format |
| 138 | + |
| 139 | +Proma stores sessions as JSONL files in `~/.proma/agent-sessions/`. Each line is a JSON object with: |
| 140 | +- `type`: `"user"` or `"assistant"` |
| 141 | +- `message.content`: array of content blocks (text, tool_use, tool_result, thinking) |
| 142 | +- `uuid`: unique message identifier |
| 143 | + |
| 144 | +The save script deduplicates by UUID and extracts human-readable text from content blocks. |
| 145 | + |
| 146 | +## Configuration |
| 147 | + |
| 148 | +| Environment Variable | Purpose | Default | |
| 149 | +|---------------------|---------|---------| |
| 150 | +| `NMEM_API_URL` | nmem server URL | From `~/.nowledge-mem/config.json` | |
| 151 | +| `NMEM_API_KEY` | nmem API key | From `~/.nowledge-mem/config.json` | |
| 152 | +| `PROMA_HOME` | Proma home directory | `~/.proma` | |
| 153 | + |
| 154 | +The hook scripts read credentials from standard nmem config (`~/.nowledge-mem/config.json`), so no duplicate configuration is needed if nmem is already set up on the machine. |
| 155 | + |
| 156 | +## Troubleshooting |
| 157 | + |
| 158 | +**MCP tools not showing up:** |
| 159 | +- Verify `mcp.json` uses `"servers"` (not `"mcpServers"`) as the top-level key |
| 160 | +- Check the API URL and key are correct |
| 161 | +- Restart Proma after changing `mcp.json` |
| 162 | + |
| 163 | +**Hooks not firing:** |
| 164 | +- Check `~/.proma/log/nmem-hook.log` for errors |
| 165 | +- Verify Python 3.9+ is installed and in PATH |
| 166 | +- Ensure hook commands use correct absolute paths |
| 167 | + |
| 168 | +**"nmem CLI not found":** |
| 169 | +- Install via `pip install nmem-cli` or the Nowledge Mem desktop app |
| 170 | +- Verify `nmem --version` works in your terminal |
| 171 | + |
| 172 | +**Session not saved:** |
| 173 | +- Run the save script manually: `echo '{"session_id":"<id>"}' | python hooks/save-to-nmem.py` |
| 174 | +- Check the log at `~/.proma/log/nmem-hook.log` |
0 commit comments