release: v0.1.3 — dual_memory_write tool + qdrant_find/qdrant_store aliases

Closes the write-path gap so supamem can be the ONLY memory MCP server per
project, replacing the upstream mcp-server-qdrant + dev_memory collection
combo for both read and write.

Added:
- dual_memory_write MCP tool — writes Markdown with YAML frontmatter to
  <project>/.claude/insights/_agent/<slug>.md, immediately upserts into the
  tuned-hybrid Qdrant collection (wait=True). Idempotent on topic via
  UUIDv5(NAMESPACE_AGENT_WRITE, slug). Path-traversal guarded; size-capped.
- qdrant_find / qdrant_store backward-compat aliases (default-on, disable
  with SUPAMEM_QDRANT_ALIASES=0). Lets existing prose referencing the
  upstream tool names keep working without rewrites.
- supamem.memory_writer public module for non-MCP callers.

Partial-failure: file is written before Qdrant upsert; if index fails the
file persists with indexed=false in the result so next `supamem index`
picks it up.

PyYAML promoted to direct dep.

208/208 tests green (20 new for memory_writer); ruff clean; twine check
PASSED.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: dzmitrys-dev

CHANGELOG.md

@@ -2,6 +2,51 @@
 
 All notable changes to `supamem` will be documented in this file.
 
+## v0.1.3 — 2026-04-29
+
+Adds the missing **write path** so supamem can serve as the *only* memory
+layer per project (no need to keep upstream `mcp-server-qdrant` alongside
+for the `qdrant-store` workflow).
+
+### Added
+
+- New `dual_memory_write` MCP tool: agents persist insights/research
+  findings mid-session. Writes a deterministic Markdown file with YAML
+  frontmatter to `<project>/.claude/insights/_agent/<slug>.md` and
+  immediately upserts it into the project's tuned-hybrid Qdrant collection
+  with `wait=True` so the very next `dual_memory_search` sees it.
+- Idempotent on `topic`: same topic → same `slugify()` slug → same on-disk
+  path → same `UUIDv5(NAMESPACE_AGENT_WRITE, slug)` Qdrant point id.
+  Re-saving overwrites in place.
+- Backward-compat aliases for upstream `mcp-server-qdrant` users:
+  `qdrant_find` (alias of `dual_memory_search`) and `qdrant_store` (alias
+  of `dual_memory_write`). Default-on; disable with
+  `SUPAMEM_QDRANT_ALIASES=0`. Lets existing prose / agent instructions
+  ("save with qdrant-store", "query qdrant-find") keep working without
+  rewrites.
+- New `supamem.memory_writer` public module: `write_memory()` for non-MCP
+  callers (CLI plugins, scripts).
+
+### Fixed
+
+- Partial-failure semantics: if Qdrant indexing fails after the on-disk
+  write succeeded, return `indexed: false` with the error message instead
+  of leaving the file unwritten — the file is still valuable and the next
+  `supamem index --target tuned` run will pick it up.
+
+### Security
+
+- Path-traversal hardened: target path resolution refuses anything that
+  doesn't `is_relative_to(project_root)`.
+- Size limits enforced: `topic <= 120`, `content <= 64K`, `description
+  <= 300`, `tags <= 10` items × 32 chars each.
+
+### Added (deps)
+
+- `PyYAML>=6.0` promoted from transitive to direct dependency
+  (`memory_writer` writes YAML frontmatter; explicit dep avoids surprise
+  removal if a transitive provider drops it).
+
 ## v0.1.2 — 2026-04-29
 
 Project-tunable regress baselines and config-resolved goldens path. Unblocks

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "supamem"
-version = "0.1.2"
+version = "0.1.3"
 description = "Project-agnostic dual-memory tooling for Claude Code, Cursor, and opencode"
 readme = "README.md"
 license = "MIT"
@@ -21,6 +21,7 @@ dependencies = [
   "langchain-text-splitters>=0.3",
   "platformdirs>=4.2",
   "packaging>=23.0",
+  "PyYAML>=6.0",
 ]
 
 [project.urls]

src/supamem/__init__.py

@@ -1,2 +1,2 @@
 """supamem — project-agnostic dual-memory tooling."""
-__version__ = "0.1.2"
+__version__ = "0.1.3"

src/supamem/mcp_server.py

@@ -196,14 +196,19 @@ async def dual_memory_search(
 
 
 def _register_dual_memory_tool(app: Any, config: ResolvedConfig) -> None:
-    """Register dual_memory_search on a FastMCP app with brand polish.
+    """Register dual_memory_search + dual_memory_write (and aliases) on a FastMCP app.
 
     - title (spec ≥ 2025-03-26) — Cursor / Claude.ai web render this.
-    - annotations.readOnlyHint=True — agent UIs hide the destructive-action confirmation.
     - description — concise; renders in tool-picker UIs.
+    - Aliases ``qdrant_find`` / ``qdrant_store`` are registered by default for
+      backward compat with the upstream ``mcp-server-qdrant`` tool names.
+      Disable with ``SUPAMEM_QDRANT_ALIASES=0``.
     """
     from mcp.server.fastmcp.tools import Tool as _FastMCPTool  # noqa: F401  (typecheck only)
 
+    aliases_enabled = os.environ.get("SUPAMEM_QDRANT_ALIASES", "1").strip() not in ("0", "false", "")
+
+    # ── Read: dual_memory_search (canonical) ────────────────────────────────
     @app.tool(
         name="dual_memory_search",
         title=_TOOL_TITLE,
@@ -218,6 +223,115 @@ async def dual_memory_search_tool(  # noqa: ARG001  (FastMCP wraps this)
     ) -> SearchResult:
         return await dual_memory_search(query=query, top_k=top_k, config=config)
 
+    # ── Write: dual_memory_write (canonical) ────────────────────────────────
+    @app.tool(
+        name="dual_memory_write",
+        title="🧠 supamem · Memory Save",
+        description=(
+            "Persist an insight, research finding, or note into the project's "
+            "dual-memory corpus. Writes a Markdown file under "
+            "<project>/.claude/insights/_agent/<slug>.md AND immediately indexes "
+            "it into Qdrant so the very next dual_memory_search sees it. "
+            "Idempotent on topic — re-saving the same topic overwrites in place."
+        ),
+    )
+    async def dual_memory_write_tool(  # noqa: ARG001
+        topic: str = Field(
+            ...,
+            description="Short topic (used as deterministic slug; max 120 chars).",
+        ),
+        content: str = Field(
+            ...,
+            description="Markdown body of the memory (max 64K chars).",
+        ),
+        description: Optional[str] = Field(
+            None,
+            description="Optional one-line description for the YAML frontmatter (max 300 chars).",
+        ),
+        tags: Optional[list[str]] = Field(
+            None,
+            description="Optional tags (max 10, each max 32 chars).",
+        ),
+    ) -> dict:
+        from supamem.memory_writer import write_memory
+
+        try:
+            res = await asyncio.to_thread(
+                write_memory,
+                topic=topic,
+                content=content,
+                description=description,
+                tags=tags,
+                config=config,
+            )
+        except ValueError as exc:
+            raise RuntimeError(f"dual_memory_write: {exc}") from None
+        return {
+            "summary": res.summary,
+            "path": res.path,
+            "topic": res.topic,
+            "slug": res.slug,
+            "indexed": res.indexed,
+            "points_added": res.points_added,
+            "error": res.error,
+        }
+
+    # ── Backward-compat aliases for upstream `mcp-server-qdrant` users ──────
+    if aliases_enabled:
+
+        @app.tool(
+            name="qdrant_find",
+            title="🧠 supamem · qdrant-find (alias)",
+            description=(
+                "Backward-compat alias for dual_memory_search. Identical behavior; "
+                "kept so prose referencing the upstream `qdrant-find` tool name "
+                "still routes correctly. Disable with SUPAMEM_QDRANT_ALIASES=0."
+            ),
+        )
+        async def qdrant_find_alias(  # noqa: ARG001
+            query: str = Field("", description="Search query (alias of dual_memory_search)."),
+            top_k: int = Field(5, description="Max chunks to return."),
+        ) -> SearchResult:
+            return await dual_memory_search(query=query, top_k=top_k, config=config)
+
+        @app.tool(
+            name="qdrant_store",
+            title="🧠 supamem · qdrant-store (alias)",
+            description=(
+                "Backward-compat alias for dual_memory_write. Identical behavior; "
+                "kept so prose referencing the upstream `qdrant-store` tool name "
+                "still routes correctly. Disable with SUPAMEM_QDRANT_ALIASES=0."
+            ),
+        )
+        async def qdrant_store_alias(  # noqa: ARG001
+            topic: str = Field(..., description="Topic (alias of dual_memory_write)."),
+            content: str = Field(..., description="Markdown body."),
+            description: Optional[str] = Field(None, description="Optional description."),
+            tags: Optional[list[str]] = Field(None, description="Optional tags."),
+        ) -> dict:
+            from supamem.memory_writer import write_memory
+
+            try:
+                res = await asyncio.to_thread(
+                    write_memory,
+                    topic=topic,
+                    content=content,
+                    description=description,
+                    tags=tags,
+                    config=config,
+                )
+            except ValueError as exc:
+                raise RuntimeError(f"qdrant_store: {exc}") from None
+            return {
+                "summary": res.summary,
+                "path": res.path,
+                "topic": res.topic,
+                "slug": res.slug,
+                "indexed": res.indexed,
+                "points_added": res.points_added,
+                "error": res.error,
+            }
+
 
 def build_app(config: ResolvedConfig) -> Any:
     """Construct a FastMCP app with the dual_memory_search tool registered."""