hmem-mcp 6.5.0 → 6.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hmem-mcp",
-  "version": "6.5.0",
+  "version": "6.5.1",
   "description": "Humanlike memory for AI agents — MCP server with 5-level lazy-loaded SQLite memory",
   "author": "Bumblebiber",
   "license": "MIT",

package/skills/hmem-write/SKILL.md

@@ -15,39 +15,26 @@ If `write_memory` is not available:
 
 ## Syntax
 
-```
-write_memory(
-  prefix: "E",
-  content: "Short Title (~50 chars)\n\nL1 body — detailed explanation, can span multiple lines\nsecond body line with more context\n\tL2 node title\n\n\tL2 body text (supports newlines)\n\tmore L2 body\n\t\tL3 detail (2 tabs)\n\t\t\tL4 raw data (3 tabs — rarely needed)"
-)
-```
+Every node has a **title** (short navigation label, shown in listings) and an optional **body** (detail shown on drill-down). Use explicit parameters — avoid blank-line tricks in `content`:
 
-**Title + Body convention (git-commit style):** Every node has a **title** (short navigation label) and an optional **body** (detailed content loaded on drill-down). Separate them with a **blank line** — just like a git commit message.
+```python
+# Preferred: explicit title + body
+write_memory(prefix="E", title="Short Title (~50 chars)", body="Full explanation here.\nCan span multiple lines.", content="\tL2 section\n\t\tL3 detail")
 
-- **Title:** The first line (L1) or first line at a given indent level (L2+). ~50 chars, like a chapter title.
-- **Body:** Everything after the blank line at the same indent level. Freetext, no special prefix needed. Shown only when the node is drilled into, not in listings.
-- **Legacy `> ` prefix:** Still works for backward compatibility, but blank-line separation is preferred.
-- **Without body:** The full text is stored as `content` and the title is auto-extracted from the first `maxTitleChars` characters.
+# Title only (no body)
+write_memory(prefix="L", title="FTS5 needs rowid-map for contentless tables", content="\tDetails\n\t\tImplication")
 
-**L1 example with body:**
+# Legacy (still works, but avoid for new entries)
+write_memory(prefix="E", content="Short Title\n\nBody text here.\n\tL2 section\n\t\tL3 detail")
 ```
-Short Error Title
 
-SQLite connection failed because .mcp.json used a relative path.
-The fix was to use an absolute path in the HMEM_PATH env var.
-	Details about reproduction
+**Parameters:**
+- **`title`** — Short label (~50 chars). Think "chapter title in a book". Shown in all listings.
+- **`body`** — Freetext detail (any length, newlines OK). Shown only on drill-down.
+- **`content`** — Tab-indented sub-nodes (L2+). When `title` is given, `content` holds only sub-nodes. In legacy mode (no `title`), `content` holds everything.
 
-	Steps: 1. Set HMEM_PATH=./hmem  2. Run hmem serve  3. Observe SQLITE_CANTOPEN
-```
-
-**L1 example without body (still works):**
-```
-SQLite connection failed due to wrong path in .mcp.json
-	Fix: use absolute path in env var
-```
+**Sub-node indentation:** 1 tab = 1 level deeper. Never use tabs for text formatting inside body — tabs are structural.
 
-**Indentation:** 1 tab = 1 level. Alternatively: 2 or 4 spaces per level (auto-detected).
-**Warning:** A tab at the start of any line always means "go one level deeper" — it is structural, not content. If you need to store code or text that contains leading tabs, use spaces instead.
 **IDs and timestamps** are assigned automatically — never write them yourself.
 
 ---
@@ -190,16 +177,18 @@ The MCP server validates that L2 nodes start with one of these names. Minimum fo
 
 **Complete P-entry example (WeatherBot):**
 
-```
+```python
 write_memory(
   prefix="P",
-  content="WeatherBot | New | Python/Discord.py | GH: user/weatherbot\n\nDiscord bot for weather forecasts — slash commands for current weather and multi-day forecasts\n\tOverview\n\t\tCurrent state\n\n\t\tScaffolding done, no commands yet. Bot connects to Discord but has no slash commands registered.\n\t\tGoals\n\n\t\tDaily/hourly forecasts via slash commands, multi-city support, embed formatting\n\t\tArchitecture\n\n\t\tDiscord slash command → OpenWeatherMap API → formatted embed. Single-file cog pattern.\n\t\tEnvironment\n\n\t\t/home/user/weatherbot, python bot.py, needs DISCORD_TOKEN + WEATHER_API_KEY in .env\n\tCodebase\n\t\tEntry point — bot.py, start: python bot.py\n\t\tCore modules\n\t\t\tweather_cog.py — WeatherCog(Cog); fetch_forecast(city: str) → discord.Embed\n\t\t\tformatter.py — format_embed(data: dict) → discord.Embed\n\t\tHelpers / Utilities\n\t\t\tapi_client.py — get_weather(city: str) → dict; wraps HTTP to OpenWeatherMap\n\t\tConfig / Constants — .env: DISCORD_TOKEN, WEATHER_API_KEY, DEFAULT_CITY\n\t\tTests — pytest, test_weather_cog.py (3 tests)\n\tUsage\n\t\tInstallation / Setup — pip install -r requirements.txt, cp .env.example .env\n\t\tCLI / API — /weather <city>, /forecast <city> (planned)\n\tContext\n\t\tInitiator — personal project, Mar 2026\n\t\tTarget audience — personal Discord server\n\t\tDependencies — discord.py, OpenWeatherMap API, aiohttp\n\tOpen tasks\n\t\tImplement /forecast command\n\n\t\tMulti-day view with daily highs/lows and weather icons per day\n\t\tAdd city autocomplete",
+  title="WeatherBot | New | Python/Discord.py | GH: user/weatherbot",
+  body="Discord bot for weather forecasts — slash commands for current weather and multi-day forecasts",
+  content="\tOverview\n\t\tCurrent state\n\t\t> Scaffolding done, no commands yet. Bot connects to Discord but has no slash commands registered.\n\t\tGoals\n\t\t> Daily/hourly forecasts via slash commands, multi-city support, embed formatting\n\t\tArchitecture\n\t\t> Discord slash command → OpenWeatherMap API → formatted embed. Single-file cog pattern.\n\t\tEnvironment\n\t\t> /home/user/weatherbot, python bot.py, needs DISCORD_TOKEN + WEATHER_API_KEY in .env\n\tCodebase\n\t\tEntry point — bot.py, start: python bot.py\n\t\tCore modules\n\t\t\tweather_cog.py — WeatherCog(Cog); fetch_forecast(city: str) → discord.Embed\n\t\t\tformatter.py — format_embed(data: dict) → discord.Embed\n\t\tHelpers / Utilities\n\t\t\tapi_client.py — get_weather(city: str) → dict; wraps HTTP to OpenWeatherMap\n\t\tConfig / Constants — .env: DISCORD_TOKEN, WEATHER_API_KEY, DEFAULT_CITY\n\t\tTests — pytest, test_weather_cog.py (3 tests)\n\tUsage\n\t\tInstallation / Setup — pip install -r requirements.txt, cp .env.example .env\n\t\tCLI / API — /weather <city>, /forecast <city> (planned)\n\tContext\n\t\tInitiator — personal project, Mar 2026\n\t\tTarget audience — personal Discord server\n\t\tDependencies — discord.py, OpenWeatherMap API, aiohttp\n\tNext Steps\n\t\tImplement /forecast command\n\t\t> Multi-day view with daily highs/lows and weather icons per day\n\t\tAdd city autocomplete",
   tags=["#discord", "#python", "#weather", "#bot"],
   links=[]
 )
 ```
 
-Note: L2 nodes use 1 tab, L3 uses 2 tabs, L4 uses 3 tabs. Separate title from body with a blank line at the same indent level. Skip empty sections — no need for placeholder text.
+Note: L2 nodes use 1 tab, L3 uses 2 tabs, L4 uses 3 tabs. Use `title`+`body` for the root entry. For body text on sub-nodes inside `content`, use the `> ` prefix (unambiguous, no blank-line tricks). Skip empty sections — no need for placeholder text.
 
 ### E-Entry Schema (auto-scaffolded)
 
@@ -291,15 +280,19 @@ write_memory(
 - Not "Fixed a bug" — instead explain root cause, fix, and impact
 
 **With title + body (recommended):**
-```
-write_memory(prefix="L", content="hmem.py Performance: Bulk-Queries statt N+1\n\nAlle Nodes in 2 Bulk-Queries laden, nicht pro Entry einzeln.\nVorher: load_nodes() pro Entry = N+1 SQLite-Connections.\n\tImplementation detail\n\n\tChanged read() to batch-fetch all nodes for visible entries in one query")
+```python
+write_memory(
+  prefix="L",
+  title="hmem.py Performance: Bulk-Queries statt N+1",
+  body="Alle Nodes in 2 Bulk-Queries laden, nicht pro Entry einzeln.\nVorher: load_nodes() pro Entry = N+1 SQLite-Connections.",
+  content="\tImplementation detail\n\t\tChanged read() to batch-fetch all nodes for visible entries in one query"
+)
 ```
 
-**Without body (simple entries, backward-compatible):**
+**Without body (simple entries, still works):**
+```python
+write_memory(prefix="E", title="SQLite connection failed due to wrong path in .mcp.json", content="\tFix: use absolute path in env var")
 ```
-write_memory(prefix="E", content="SQLite connection failed due to wrong path in .mcp.json\n\tFix: use absolute path in env var")
-```
-Title auto-extracted: `"SQLite connection failed due to wrong path in .mc"`
 
 ---
 
@@ -403,10 +396,21 @@ Use `update_memory` and `append_memory` to modify entries without deleting and r
 
 Updates the text of a single node. Children are **not** touched.
 
-```
-update_memory(id="L0003", content="Corrected L1 summary — new wording")
-update_memory(id="L0003.2", content="Fixed L2 detail")
-update_memory(id="D0010", content="New L1", links=["E0042"])  # also update links
+```python
+# Update title only
+update_memory(id="L0003", content="Corrected summary — new wording")
+
+# Update body only (title preserved automatically)
+update_memory(id="L0003", body="New detailed explanation here.")
+
+# Update both title and body
+update_memory(id="L0003", content="New short title", body="New detailed body text.")
+
+# Update sub-node
+update_memory(id="L0003.2", content="Fixed sub-node title", body="Sub-node body.")
+
+# Also update links
+update_memory(id="D0010", content="New title", links=["E0042"])
 ```
 
 Use when: the wording is wrong, outdated, or needs clarification.
@@ -415,34 +419,21 @@ Use when: the wording is wrong, outdated, or needs clarification.
 
 Appends new child nodes under an existing root or node. Existing children are preserved.
 
-Content indentation is **relative to the parent** — 0 tabs = direct child of `id`.
-Body works the same as in `write_memory` — blank line separates title from body.
+```python
+# Preferred: explicit title + body
+append_memory(id="L0003", title="New finding", body="Detailed explanation of what was found.\nCan span multiple lines.")
 
-> **Schema enforcement:** For entries with a defined schema (e.g., all P-entries), appending
-> to the root (e.g., `id="P0029"`) is **blocked** — that would create a new L2 section outside
-> the schema. You must target a specific section: `append_memory(id="P0029.3", content="...")`.
-> For entries without a schema (L, D, E, etc. by default), root appends are allowed.
+# With sub-nodes (complex mode)
+append_memory(id="L0003", content="New finding\n\tSub-detail\n\t\tDeep detail")
 
+# Append to a specific section node
+append_memory(id="P0029.3", title="New usage example", body="Run: hmem serve --port 3100")
 ```
-append_memory(
-  id="L0003",
-  content="New finding discovered later\n\nDetailed explanation of what was found and why it matters.\nThis can span multiple lines.\n\tSub-detail about it"
-)
-# → adds L0003.N (L2 with title + body) and L0003.N.1 (L3)
-# ↑ only works if L has no schema defined; use L0003.N for schema-constrained entries
 
-append_memory(
-  id="P0029.3",
-  content="New detail in the Usage section"
-)
-# → adds P0029.3.M (L3 under section .3) — correct way for schema-constrained entries
-
-append_memory(
-  id="L0003.2",
-  content="Extra note under L0003.2"
-)
-# → adds L0003.2.M (L3)
-```
+> **Schema enforcement:** For entries with a defined schema (e.g., all P-entries), appending
+> to the root (e.g., `id="P0029"`) is **blocked** — that would create a new L2 section outside
+> the schema. You must target a specific section: `append_memory(id="P0029.3", ...)`.
+> For entries without a schema (L, D, E, etc. by default), root appends are allowed.
 
 Use when: you have new context to add without replacing what's there.