Merge pull request #151 from nowledge-co/dev_0615

feat: Pi and Hermes support

Author: wey-gu

README.md

@@ -37,6 +37,8 @@ Each directory is a standalone integration. Pick the one that matches your tool.
 | **[OpenClaw Plugin](nowledge-mem-openclaw-plugin)** | `openclaw plugins install @nowledge/openclaw-nowledge-mem` | Full memory lifecycle with memory tools, thread tools, automatic capture, and distillation. |
 | **[Alma Plugin](nowledge-mem-alma-plugin)** | Search Nowledge in Alma official Plugin marketplace | Alma-native plugin with Working Memory, thread-aware recall, structured saves, and optional auto-capture. |
 | **[Bub Plugin](nowledge-mem-bub-plugin)** | `pip install nowledge-mem-bub` | Bub-native plugin: cross-tool knowledge, auto-capture via save_state, Working Memory, and graph exploration. |
+| **[Pi Package](nowledge-mem-pi-package)** | `pi install npm:nowledge-mem-pi` | Five composable skills for Working Memory, routed recall, distillation, and resumable handoffs in Pi. |
+| **[Hermes Agent](nowledge-mem-hermes)** | Add MCP server to `~/.hermes/config.yaml` | Cross-tool knowledge in Hermes via MCP: search, save, Working Memory, and thread history. |
 | **[Raycast Extension](nowledge-mem-raycast)** | Search Nowledge in Raycast Extension Store | Search memories from Raycast launcher. |
 | **[Claude Desktop](https://github.com/nowledge-co/claude-dxt)** | Download from [nowled.ge/claude-dxt](https://nowled.ge/claude-dxt), double-click `.mcpb` file | One-click extension for Claude Desktop with memory search, save, and update. |
 | **[Browser Extension](https://chromewebstore.google.com/detail/nowledge-memory-exchange/kjgpkgodplgakbeanoifnlpkphemcbmh)** | Install from Chrome Web Store | Side-panel capture for ChatGPT, Claude, Gemini, Perplexity, and other web AI surfaces. |

integrations.json

@@ -286,6 +286,73 @@
       "skills": ["nowledge-mem"],
       "slashCommands": []
     },
+    {
+      "id": "pi",
+      "name": "Pi",
+      "category": "coding",
+      "type": "skills",
+      "version": "0.1.0",
+      "directory": "nowledge-mem-pi-package",
+      "transport": "cli",
+      "capabilities": {
+        "workingMemory": true,
+        "search": true,
+        "distill": true,
+        "autoRecall": false,
+        "autoCapture": false,
+        "graphExploration": false,
+        "status": true
+      },
+      "threadSave": {
+        "method": "handoff-only",
+        "note": "Pi does not have a native transcript importer; save-thread creates a structured handoff summary"
+      },
+      "install": {
+        "command": "pi install npm:nowledge-mem-pi",
+        "updateCommand": "pi install npm:nowledge-mem-pi@latest",
+        "detectionHint": "Running as Pi agent; ~/.pi/ exists",
+        "docsUrl": "/docs/integrations/pi"
+      },
+      "toolNaming": {
+        "convention": "cli-direct",
+        "note": "Skills teach agent to invoke nmem CLI directly"
+      },
+      "skills": ["read-working-memory", "search-memory", "distill-memory", "save-thread", "status"],
+      "slashCommands": []
+    },
+    {
+      "id": "hermes",
+      "name": "Hermes Agent",
+      "category": "coding",
+      "type": "connector",
+      "version": "0.1.0",
+      "directory": "nowledge-mem-hermes",
+      "transport": "mcp",
+      "capabilities": {
+        "workingMemory": true,
+        "search": true,
+        "distill": true,
+        "autoRecall": false,
+        "autoCapture": false,
+        "graphExploration": true,
+        "status": false
+      },
+      "threadSave": {
+        "method": "mcp-tool",
+        "note": "thread_persist available via MCP; full transcript depends on client capabilities"
+      },
+      "install": {
+        "command": "Add nowledge-mem MCP server to ~/.hermes/config.yaml",
+        "detectionHint": "Running as Hermes agent; ~/.hermes/ exists",
+        "docsUrl": "/docs/integrations/hermes"
+      },
+      "toolNaming": {
+        "convention": "mcp-backend",
+        "note": "MCP tools defined by backend (memory_search, memory_add, etc.)"
+      },
+      "skills": [],
+      "slashCommands": []
+    },
     {
       "id": "npx-skills",
       "name": "npx Skills",

nowledge-mem-hermes/AGENTS.md

@@ -0,0 +1,89 @@
+# Nowledge Mem for Hermes
+
+You have access to the user's knowledge graph through MCP tools provided by the `nowledge-mem` server.
+
+## Working Memory
+
+At session start, load the user's current context:
+
+```
+read_working_memory
+```
+
+This returns priorities, recent decisions, and open questions. Reference relevant parts naturally as the conversation progresses. If it returns empty, mention there is no briefing yet and continue.
+
+Do not re-read unless the user asks or the session context changes materially.
+
+## Proactive Search
+
+Search when past insights would improve the response. Do not wait for the user to say "search my memory".
+
+**Search when:**
+- The user references previous work, a prior fix, or an earlier decision
+- The task resumes a named feature, bug, refactor, or subsystem
+- A debugging pattern resembles something solved before
+- The user asks for rationale, preferences, or procedures
+- The user uses recall language: "that approach", "like before", "the pattern we used"
+
+**Skip when:**
+- Fundamentally new topic with no prior history
+- Generic syntax or API questions answerable from documentation
+- User explicitly asks for a fresh perspective
+
+```
+memory_search query="your search query"
+```
+
+For past conversations specifically:
+
+```
+thread_search query="your search query"
+thread_fetch_messages thread_id="<id>" limit=8
+```
+
+## Saving Knowledge
+
+Save proactively when the conversation produces a decision, procedure, learning, or important context. Do not wait to be asked.
+
+```
+memory_add content="What was decided and why" title="Descriptive title" unit_type="decision" labels=["relevant-label"] importance=0.8
+```
+
+**Good candidates:** architectural decisions with rationale, repeatable procedures, lessons from debugging, durable preferences, plans that future sessions will need.
+
+**Quality bar:**
+- Importance 0.8 to 1.0: major decisions, architectural choices, critical learnings
+- Importance 0.5 to 0.7: useful patterns, conventions, secondary decisions
+- Importance 0.3 to 0.4: minor notes, preferences, contextual observations
+
+One strong memory is better than three weak ones.
+
+Unit types: `fact`, `preference`, `decision`, `plan`, `procedure`, `learning`, `context`, `event`
+
+## Add vs Update
+
+Search first to avoid duplicates. If an existing memory already captures the same concept and the new information refines it, update instead of creating a new one:
+
+```
+memory_search query="the concept you're about to save"
+memory_update memory_id="<existing_id>" content="Updated content with new information"
+```
+
+## Thread Tools
+
+Save the current conversation when the user asks:
+
+```
+thread_persist summary="Brief description of what was discussed"
+```
+
+Browse past conversations to recover context:
+
+```
+thread_search query="topic from a previous session"
+thread_fetch_messages thread_id="<id>" limit=8
+```
+
+## Labels
+
+Use `list_memory_labels` to see existing categories before creating new labels. Reuse existing labels when they fit.

nowledge-mem-hermes/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## [0.1.0] - 2026-03-31
+
+### Added
+
+- MCP-based integration connecting Hermes Agent to the Nowledge Mem knowledge graph.
+- Full MCP tool access: memory search, add, update, delete, Working Memory, thread operations.
+- Behavioral guidance (`AGENTS.md`) for project-level memory behavior in Hermes sessions.
+- Remote access configuration for multi-machine setups.

nowledge-mem-hermes/README.md

@@ -0,0 +1,101 @@
+# Nowledge Mem for Hermes Agent
+
+> Cross-tool knowledge, accessible in every Hermes session. Your decisions, procedures, and context travel with you.
+
+Hermes has its own memory and learning system. Nowledge Mem complements it with knowledge that spans tools: insights from Claude Code, Cursor, Codex, Gemini, and every other environment you work in. One knowledge graph, available everywhere.
+
+## What you get
+
+- **Start every session informed.** Hermes loads your Working Memory briefing: current priorities, recent decisions, open questions.
+- **The agent searches for you.** When past context would improve the answer, Hermes finds it through your knowledge graph without being asked.
+- **Insights stick around.** Key decisions and learnings are saved to Nowledge Mem, ready for any future session in any tool.
+- **Full session history.** Save Hermes conversations as structured threads you can search later.
+
+## Prerequisites
+
+1. **Nowledge Mem desktop app** running (or the server accessible on port 14242)
+2. **Hermes Agent** installed and configured
+
+## Setup
+
+Add the Nowledge Mem MCP server to your Hermes configuration:
+
+```yaml title="~/.hermes/config.yaml"
+mcp_servers:
+  nowledge-mem:
+    url: "http://127.0.0.1:14242/mcp"
+    timeout: 120
+```
+
+Restart Hermes to pick up the new server.
+
+## Verify
+
+Start a new Hermes session and ask:
+
+> Search my memories for recent decisions.
+
+Hermes should call `memory_search` and return results from your knowledge graph. If Mem is not running, you will see a connection error.
+
+## Update
+
+The MCP server runs inside Nowledge Mem. When you update the desktop app, all MCP tools update automatically. No changes to your Hermes config needed.
+
+## MCP tools
+
+These tools are available to Hermes once the MCP server is connected:
+
+| Tool | Purpose |
+|------|---------|
+| `read_working_memory` | Load your daily context briefing |
+| `memory_search` | Search memories and distilled knowledge |
+| `memory_add` | Save a new memory |
+| `memory_update` | Refine an existing memory |
+| `memory_delete` | Remove a memory |
+| `thread_search` | Search past conversations |
+| `thread_fetch_messages` | Read messages from a specific thread |
+| `thread_persist` | Save a conversation thread |
+| `list_memory_labels` | Browse memory categories |
+
+Additional tools for graph exploration, source analysis, and knowledge processing are available depending on your server configuration.
+
+## Behavioral guidance (optional)
+
+For stronger memory behavior in a specific project, copy the included `AGENTS.md` into your project root as `AGENTS.md` or `HERMES.md`. Hermes reads these files for project-level context.
+
+```bash
+cp AGENTS.md /path/to/your/project/HERMES.md
+```
+
+This tells Hermes when to search, when to save, and how to use Working Memory. Without it, the MCP tools still work, but Hermes relies on its own judgment for when to call them.
+
+## Remote access
+
+If Nowledge Mem runs on another machine, update the MCP server URL:
+
+```yaml title="~/.hermes/config.yaml"
+mcp_servers:
+  nowledge-mem:
+    url: "https://your-server:14242/mcp"
+    timeout: 120
+```
+
+Ensure the remote server has API access enabled. See [Remote Access](https://mem.nowledge.co/docs/remote-access) for setup details.
+
+## Troubleshooting
+
+- **"Cannot connect to MCP server"**: Verify the Nowledge Mem desktop app is running and the server is listening on port 14242. Check with `curl http://127.0.0.1:14242/health`.
+- **Tools not appearing**: Restart Hermes after editing `config.yaml`. Confirm the `mcp_servers` block is properly indented.
+- **Slow responses**: The default timeout of 120 seconds covers deep search. If searches consistently time out, check server performance or network latency for remote setups.
+- **No results from search**: Nowledge Mem may be empty. Add a few memories first through the desktop app or another integration, then try again.
+
+## Links
+
+- [Hermes integration guide](https://mem.nowledge.co/docs/integrations/hermes)
+- [Documentation](https://mem.nowledge.co/docs/integrations)
+- [Discord](https://nowled.ge/discord)
+- [GitHub](https://github.com/nowledge-co/community)
+
+---
+
+Made with care by [Nowledge Labs](https://nowledge-labs.ai)

nowledge-mem-npx-skills/skills/check-integration/SKILL.md

@@ -43,6 +43,8 @@ The canonical source for this table is `community/integrations.json`.
 | **Droid** | Running inside Droid (Factory) | Add nowledge-co/community marketplace, install nowledge-mem@nowledge-community | [Guide](https://mem.nowledge.co/docs/integrations/droid) |
 | **Codex CLI** | Running as Codex CLI agent; `~/.codex/` exists | Copy `nowledge-mem-codex-plugin` to `~/.codex/plugins/nowledge-mem` | [Guide](https://mem.nowledge.co/docs/integrations/codex-cli) |
 | **Bub** | Running inside Bub | `pip install nowledge-mem-bub` | [Guide](https://mem.nowledge.co/docs/integrations/bub) |
+| **Pi** | Running as Pi agent; `~/.pi/` exists | `pi install npm:nowledge-mem-pi` | [Guide](https://mem.nowledge.co/docs/integrations/pi) |
+| **Hermes Agent** | Running as Hermes agent; `~/.hermes/` exists | Add MCP server to `~/.hermes/config.yaml` | [Guide](https://mem.nowledge.co/docs/integrations/hermes) |
 
 If the agent is not listed above, the npx skills you already have are the best option. They work everywhere via the `nmem` CLI.
 

nowledge-mem-pi-package/AGENTS.md

@@ -0,0 +1,73 @@
+# Nowledge Mem for Pi
+
+You have access to the user's cross-tool knowledge through the `nmem` CLI and five installed skills: `read-working-memory`, `search-memory`, `distill-memory`, `save-thread`, and `status`.
+
+## Working Memory at Session Start
+
+Load the user's current context at the beginning of every session:
+
+```bash
+nmem --json wm read
+```
+
+If it returns `exists: false`, mention there's no briefing yet and continue. Don't re-read during the same session unless the user asks.
+
+## Proactive Search
+
+Search when the task connects to prior work, the user references a past decision, or context from before would improve the answer. Don't search speculatively for every message.
+
+```bash
+nmem --json m search "query"
+```
+
+Use `--mode deep` when the first pass returns weak results or the query is conceptual.
+
+## Retrieval Routing
+
+Use memory search for distilled knowledge (decisions, procedures, preferences). Use thread search for past conversations:
+
+```bash
+nmem --json t search "query" --limit 5
+nmem --json t show <thread_id> --limit 8 --offset 0 --content-limit 1200
+```
+
+Load threads progressively. Increase `--offset` only when the user needs more.
+
+If a memory result includes `source_thread`, inspect the original conversation with `nmem --json t show <thread_id> --limit 8 --offset 0 --content-limit 1200`.
+
+## Autonomous Save
+
+Save proactively when the conversation produces a decision, procedure, learning, or important context. Don't wait for the user to ask.
+
+```bash
+nmem --json m add "content" -t "Title" --unit-type decision -i 0.8
+```
+
+Unit types: `fact`, `preference`, `decision`, `plan`, `procedure`, `learning`, `context`, `event`.
+
+Use `-l` to attach labels for easier retrieval: `nmem --json m add "content" -t "Title" --unit-type decision -i 0.8 -l backend -l auth`.
+
+## Add vs Update
+
+Search before saving to avoid duplicates. If a memory already captures the same concept and the new information refines it, update it:
+
+```bash
+nmem --json m update <memory_id> -c "updated content"
+```
+
+One strong memory is better than three weak ones.
+
+## Thread Save Honesty
+
+Pi does not have a native transcript importer. When the user asks to save the session, create a structured handoff summary using `nmem --json t create`. Be transparent: this is a curated summary, not a verbatim transcript. Include goals, decisions, files touched, risks, and next steps.
+
+```bash
+nmem --json t create \
+  -t "Session Handoff - <topic>" \
+  -c "Goal: ... Decisions: ... Files: ... Risks: ... Next: ..." \
+  -s generic-agent
+```
+
+## Remote Configuration
+
+If Nowledge Mem runs on a different machine, credentials live in `~/.nowledge-mem/config.json` with `apiUrl` and `apiKey` fields. Environment variables `NMEM_API_URL` and `NMEM_API_KEY` override the config file.

nowledge-mem-pi-package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to the Nowledge Mem Pi package will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-03-31
+
+### Added
+
+- Initial release with five skills:
+  - `read-working-memory`: Daily briefing with focus areas, priorities, and recent changes
+  - `search-memory`: Semantic search across memories and past conversations
+  - `distill-memory`: Save decisions, procedures, and insights as durable memories
+  - `save-thread`: Structured handoff summaries for session continuity
+  - `status`: Server connectivity check
+- Behavioral guidance companion (`AGENTS.md`)
+- Pi package manifest for `pi install npm:nowledge-mem-pi`