waymark-memory 0.3.0__tar.gz

waymark_memory-0.3.0/.gitignore

@@ -0,0 +1,26 @@
+.venv/
+.wheel-smoke/
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+dist/
+build/
+site/
+*.egg-info/
+
+# Local runtime state
+.waymark-local/
+.env
+.env.*
+
+# OS/editor noise
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/

waymark_memory-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Waymark Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

waymark_memory-0.3.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: waymark-memory
+Version: 0.3.0
+Summary: A local-first terminal companion for personal memory, reflection, and decisions.
+Project-URL: Homepage, https://shusingh.github.io/waymark/
+Project-URL: Documentation, https://shusingh.github.io/waymark/
+Project-URL: Repository, https://github.com/shusingh/waymark
+Project-URL: Issues, https://github.com/shusingh/waymark/issues
+Author: Waymark Contributors
+License: MIT
+License-File: LICENSE
+Keywords: local-first,memory,notes,reflection,sqlite,terminal
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Text Processing
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: platformdirs>=4.2
+Requires-Dist: rich>=13.7
+Requires-Dist: textual>=0.80
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pypdf>=4.0; extra == 'dev'
+Requires-Dist: pytest>=8.2; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs-typer2[mkdocs]>=0.1; extra == 'docs'
+Requires-Dist: mkdocs>=1.6; extra == 'docs'
+Provides-Extra: pdf
+Requires-Dist: pypdf>=4.0; extra == 'pdf'
+Description-Content-Type: text/markdown
+
+# Waymark
+
+Waymark is a local-first terminal companion for capturing personal memories,
+tracking decisions, reflecting on patterns, and asking grounded questions about
+your life over time.
+
+```text
+capture messy thought -> structure memory card -> store locally -> retrieve with sources -> reflect over time
+```
+
+Full documentation lives at **https://shusingh.github.io/waymark/**.
+The PyPI package name is **`waymark-memory`**; the installed command remains
+**`waymark`**.
+The complete CLI reference is generated from the Typer app, so use the docs site
+instead of hand-maintained command lists.
+
+## What Works
+
+- Guided Textual interface for today, capture, ask, timeline, memory detail,
+  reflection, decisions, import, export, backup, and doctor checks.
+- Local SQLite storage with source citations, saved reflections, linked
+  decisions, local backups, and portable bundles.
+- Explicit imports for Markdown, text, PDF text layers, DOCX paragraphs, and
+  bounded preview-first folder batches.
+- Optional local AI through Ollama for memory structuring and semantic retrieval.
+
+## Install
+
+Recommended install:
+
+```bash
+pipx install waymark-memory
+waymark --version
+```
+
+Current GitHub Release:
+
+```bash
+python -m pip install https://github.com/shusingh/waymark/releases/download/v0.3.0/waymark_memory-0.3.0-py3-none-any.whl
+waymark --version
+```
+
+Platform-specific commands are in
+[Installation & Updates](docs/guides/installation.md).
+
+From source on Windows PowerShell:
+
+```powershell
+py -m venv .venv
+.\.venv\Scripts\Activate.ps1
+python -m pip install -e ".[dev,docs,pdf]"
+```
+
+From source on macOS/Linux:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -e ".[dev,docs,pdf]"
+```
+
+## First Minute
+
+```bash
+waymark
+waymark today
+waymark capture --type project "Shipped the first import flow today."
+waymark timeline
+waymark ask "import flow"
+waymark reflect --period week
+```
+
+Start with [Getting Started](docs/getting-started.md), or open the live
+[CLI reference](https://shusingh.github.io/waymark/reference/cli/).
+
+## Development
+
+Runtime data defaults to `~/.waymark`. For local development, keep test data out
+of your real profile:
+
+```powershell
+$env:WAYMARK_HOME = "D:\Code\waymark\.waymark-local\runtime"
+```
+
+Before committing code changes:
+
+```bash
+ruff check .
+mypy src
+pytest -q
+mkdocs build --strict
+python -m build
+python -m twine check dist/*
+```
+
+CI and release jobs also run a fresh wheel install smoke test:
+
+```bash
+python -m venv .wheel-smoke
+. .wheel-smoke/bin/activate
+python -m pip install dist/*.whl
+waymark --version
+```
+
+## Product Guardrails
+
+- Local-first by default.
+- Manual capture works without AI models.
+- AI-generated summaries, tags, and reflections require user confirmation.
+- Answers must cite saved memories or imported sources.
+- No large model downloads, file scans, OCR, or indexing jobs without explicit
+  approval.

waymark_memory-0.3.0/README.md

@@ -0,0 +1,112 @@
+# Waymark
+
+Waymark is a local-first terminal companion for capturing personal memories,
+tracking decisions, reflecting on patterns, and asking grounded questions about
+your life over time.
+
+```text
+capture messy thought -> structure memory card -> store locally -> retrieve with sources -> reflect over time
+```
+
+Full documentation lives at **https://shusingh.github.io/waymark/**.
+The PyPI package name is **`waymark-memory`**; the installed command remains
+**`waymark`**.
+The complete CLI reference is generated from the Typer app, so use the docs site
+instead of hand-maintained command lists.
+
+## What Works
+
+- Guided Textual interface for today, capture, ask, timeline, memory detail,
+  reflection, decisions, import, export, backup, and doctor checks.
+- Local SQLite storage with source citations, saved reflections, linked
+  decisions, local backups, and portable bundles.
+- Explicit imports for Markdown, text, PDF text layers, DOCX paragraphs, and
+  bounded preview-first folder batches.
+- Optional local AI through Ollama for memory structuring and semantic retrieval.
+
+## Install
+
+Recommended install:
+
+```bash
+pipx install waymark-memory
+waymark --version
+```
+
+Current GitHub Release:
+
+```bash
+python -m pip install https://github.com/shusingh/waymark/releases/download/v0.3.0/waymark_memory-0.3.0-py3-none-any.whl
+waymark --version
+```
+
+Platform-specific commands are in
+[Installation & Updates](docs/guides/installation.md).
+
+From source on Windows PowerShell:
+
+```powershell
+py -m venv .venv
+.\.venv\Scripts\Activate.ps1
+python -m pip install -e ".[dev,docs,pdf]"
+```
+
+From source on macOS/Linux:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -e ".[dev,docs,pdf]"
+```
+
+## First Minute
+
+```bash
+waymark
+waymark today
+waymark capture --type project "Shipped the first import flow today."
+waymark timeline
+waymark ask "import flow"
+waymark reflect --period week
+```
+
+Start with [Getting Started](docs/getting-started.md), or open the live
+[CLI reference](https://shusingh.github.io/waymark/reference/cli/).
+
+## Development
+
+Runtime data defaults to `~/.waymark`. For local development, keep test data out
+of your real profile:
+
+```powershell
+$env:WAYMARK_HOME = "D:\Code\waymark\.waymark-local\runtime"
+```
+
+Before committing code changes:
+
+```bash
+ruff check .
+mypy src
+pytest -q
+mkdocs build --strict
+python -m build
+python -m twine check dist/*
+```
+
+CI and release jobs also run a fresh wheel install smoke test:
+
+```bash
+python -m venv .wheel-smoke
+. .wheel-smoke/bin/activate
+python -m pip install dist/*.whl
+waymark --version
+```
+
+## Product Guardrails
+
+- Local-first by default.
+- Manual capture works without AI models.
+- AI-generated summaries, tags, and reflections require user confirmation.
+- Answers must cite saved memories or imported sources.
+- No large model downloads, file scans, OCR, or indexing jobs without explicit
+  approval.

waymark_memory-0.3.0/pyproject.toml

@@ -0,0 +1,86 @@
+[build-system]
+requires = ["hatchling<1.30"]
+build-backend = "hatchling.build"
+
+[project]
+name = "waymark-memory"
+version = "0.3.0"
+description = "A local-first terminal companion for personal memory, reflection, and decisions."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [
+  { name = "Waymark Contributors" }
+]
+keywords = ["local-first", "memory", "notes", "reflection", "sqlite", "terminal"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: End Users/Desktop",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Text Processing",
+  "Topic :: Utilities"
+]
+dependencies = [
+  "platformdirs>=4.2",
+  "rich>=13.7",
+  "typer>=0.12",
+  "textual>=0.80"
+]
+
+[project.urls]
+Homepage = "https://shusingh.github.io/waymark/"
+Documentation = "https://shusingh.github.io/waymark/"
+Repository = "https://github.com/shusingh/waymark"
+Issues = "https://github.com/shusingh/waymark/issues"
+
+[project.optional-dependencies]
+pdf = [
+  "pypdf>=4.0"
+]
+docs = [
+  "mkdocs>=1.6",
+  "mkdocs-material>=9.5",
+  "mkdocs-typer2[mkdocs]>=0.1"
+]
+dev = [
+  "build>=1.2",
+  "mypy>=1.10",
+  "pypdf>=4.0",
+  "pytest>=8.2",
+  "ruff>=0.5",
+  "twine>=5.0"
+]
+
+[project.scripts]
+waymark = "waymark.cli:app"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/waymark"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "src/waymark",
+  "README.md",
+  "LICENSE",
+  "pyproject.toml"
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_unused_configs = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

waymark_memory-0.3.0/src/waymark/__init__.py

@@ -0,0 +1,3 @@
+"""Waymark package."""
+
+__version__ = "0.3.0"

waymark_memory-0.3.0/src/waymark/ai.py

@@ -0,0 +1,288 @@
+"""Optional local AI helpers for memory structuring."""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any, cast
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+from waymark.memory import MemoryDraft, fallback_summary, fallback_title, parse_tags
+
+DEFAULT_OLLAMA_ENDPOINT = "http://127.0.0.1:11434"
+MAX_MODEL_TAGS = 5
+MAX_TAG_LENGTH = 40
+MAX_MEMORY_TYPE_LENGTH = 32
+
+MEMORY_STRUCTURE_SYSTEM_PROMPT = """You structure one personal memory.
+Return compact JSON only with: title, summary, type, tags.
+Do not add facts that are not present in the memory.
+Use 2-5 lowercase tags."""
+
+
+class LocalAiError(RuntimeError):
+    """Raised when an optional local AI draft cannot be produced."""
+
+
+def structure_memory_with_ollama(
+    raw_text: str,
+    *,
+    memory_type: str,
+    raw_tags: str,
+    model: str,
+    endpoint: str = DEFAULT_OLLAMA_ENDPOINT,
+    timeout_seconds: float = 30,
+) -> MemoryDraft:
+    """Ask Ollama for a memory draft and parse it into Waymark's draft shape."""
+
+    response_text = ollama_chat(
+        model=model,
+        messages=[
+            {"role": "system", "content": MEMORY_STRUCTURE_SYSTEM_PROMPT},
+            {
+                "role": "user",
+                "content": build_memory_structure_prompt(
+                    raw_text,
+                    memory_type=memory_type,
+                    raw_tags=raw_tags,
+                ),
+            },
+        ],
+        endpoint=endpoint,
+        timeout_seconds=timeout_seconds,
+    )
+    return parse_memory_structure_response(
+        response_text,
+        raw_text=raw_text,
+        fallback_memory_type=memory_type,
+        raw_tags=raw_tags,
+    )
+
+
+def embed_text_with_ollama(
+    text: str,
+    *,
+    model: str,
+    endpoint: str = DEFAULT_OLLAMA_ENDPOINT,
+    timeout_seconds: float = 30,
+) -> tuple[float, ...]:
+    """Ask Ollama for one embedding vector using the current /api/embed endpoint."""
+
+    payload = {
+        "model": model,
+        "input": text,
+    }
+    request = Request(
+        f"{endpoint.rstrip('/')}/api/embed",
+        data=json.dumps(payload).encode("utf-8"),
+        headers={"Content-Type": "application/json"},
+        method="POST",
+    )
+
+    try:
+        response: Any = urlopen(request, timeout=timeout_seconds)
+        with response:
+            body = cast(bytes, response.read())
+    except HTTPError as error:
+        raise LocalAiError(f"Ollama returned HTTP {error.code}.") from error
+    except URLError as error:
+        raise LocalAiError(f"Ollama is not reachable: {error.reason}.") from error
+    except TimeoutError as error:
+        raise LocalAiError("Ollama request timed out.") from error
+    except OSError as error:
+        raise LocalAiError(str(error)) from error
+
+    return parse_ollama_embed_response(body)
+
+
+def parse_ollama_embed_response(body: bytes) -> tuple[float, ...]:
+    try:
+        data = json.loads(body.decode("utf-8"))
+        embeddings = data["embeddings"]
+    except (KeyError, TypeError, UnicodeDecodeError, json.JSONDecodeError) as error:
+        raise LocalAiError("Ollama returned an unexpected embedding response shape.") from error
+
+    if (
+        not isinstance(embeddings, list)
+        or not embeddings
+        or not isinstance(embeddings[0], list)
+        or not embeddings[0]
+    ):
+        raise LocalAiError("Ollama returned an empty embedding vector.")
+
+    try:
+        return tuple(float(value) for value in embeddings[0])
+    except (TypeError, ValueError) as error:
+        raise LocalAiError("Ollama returned a non-numeric embedding vector.") from error
+
+
+def build_memory_structure_prompt(raw_text: str, *, memory_type: str, raw_tags: str) -> str:
+    return (
+        "Draft a memory card for this saved memory.\n"
+        f"Requested type: {memory_type.strip() or 'daily'}\n"
+        f"User tags: {raw_tags.strip() or 'none'}\n\n"
+        "Memory:\n"
+        f"{raw_text.strip()}"
+    )
+
+
+def ollama_chat(
+    *,
+    model: str,
+    messages: list[dict[str, str]],
+    endpoint: str = DEFAULT_OLLAMA_ENDPOINT,
+    timeout_seconds: float = 30,
+) -> str:
+    payload = {
+        "model": model,
+        "messages": messages,
+        "stream": False,
+        "format": "json",
+    }
+    request = Request(
+        f"{endpoint.rstrip('/')}/api/chat",
+        data=json.dumps(payload).encode("utf-8"),
+        headers={"Content-Type": "application/json"},
+        method="POST",
+    )
+
+    try:
+        response: Any = urlopen(request, timeout=timeout_seconds)
+        with response:
+            body = cast(bytes, response.read())
+    except HTTPError as error:
+        raise LocalAiError(f"Ollama returned HTTP {error.code}.") from error
+    except URLError as error:
+        raise LocalAiError(f"Ollama is not reachable: {error.reason}.") from error
+    except TimeoutError as error:
+        raise LocalAiError("Ollama request timed out.") from error
+    except OSError as error:
+        raise LocalAiError(str(error)) from error
+
+    try:
+        data = json.loads(body.decode("utf-8"))
+        content = data["message"]["content"]
+    except (KeyError, TypeError, UnicodeDecodeError, json.JSONDecodeError) as error:
+        raise LocalAiError("Ollama returned an unexpected response shape.") from error
+
+    if not isinstance(content, str) or not content.strip():
+        raise LocalAiError("Ollama returned an empty memory draft.")
+    return content
+
+
+def parse_memory_structure_response(
+    response_text: str,
+    *,
+    raw_text: str,
+    fallback_memory_type: str,
+    raw_tags: str = "",
+) -> MemoryDraft:
+    data = parse_json_object(response_text)
+    clean_text = raw_text.strip()
+    fallback_type = normalize_memory_type(fallback_memory_type)
+    clean_type = normalize_memory_type(
+        data.get("type") or data.get("memory_type"),
+        fallback=fallback_type,
+    )
+    model_tags = normalize_model_tags(data.get("tags"))
+    tags = tuple(sorted(set(parse_tags(raw_tags)) | set(model_tags)))
+
+    return MemoryDraft(
+        raw_text=clean_text,
+        memory_type=clean_type,
+        title=clean_text_field(data.get("title"), fallback=fallback_title(clean_text), limit=72),
+        summary=clean_text_field(
+            data.get("summary"),
+            fallback=fallback_summary(clean_text),
+            limit=240,
+        ),
+        tags=tags,
+    )
+
+
+def parse_json_object(response_text: str) -> dict[str, Any]:
+    stripped = response_text.strip()
+    if stripped.startswith("```"):
+        stripped = strip_code_fence(stripped)
+
+    start = stripped.find("{")
+    end = stripped.rfind("}")
+    if start == -1 or end == -1 or end < start:
+        raise LocalAiError("Local AI did not return a JSON object.")
+
+    payload = stripped[start : end + 1]
+    try:
+        data = json.loads(payload)
+    except json.JSONDecodeError as error:
+        repaired_payload = repair_json_payload(payload)
+        try:
+            data = json.loads(repaired_payload)
+        except json.JSONDecodeError:
+            raise LocalAiError("Local AI returned invalid JSON.") from error
+    if not isinstance(data, dict):
+        raise LocalAiError("Local AI did not return a JSON object.")
+    return cast(dict[str, Any], data)
+
+
+def strip_code_fence(text: str) -> str:
+    lines = text.splitlines()
+    if len(lines) >= 2 and lines[0].startswith("```") and lines[-1].strip() == "```":
+        return "\n".join(lines[1:-1]).strip()
+    return text
+
+
+def normalize_model_tags(value: object) -> tuple[str, ...]:
+    if isinstance(value, str):
+        tags = parse_tags(value)
+        return clean_model_tags(tags)
+    if isinstance(value, list):
+        tags = parse_tags(",".join(str(item) for item in value if str(item).strip()))
+        return clean_model_tags(tags)
+    return ()
+
+
+def clean_model_tags(tags: tuple[str, ...]) -> tuple[str, ...]:
+    clean_tags = tuple(
+        normalized
+        for tag in tags
+        if (normalized := normalize_slug(tag, max_length=MAX_TAG_LENGTH))
+    )
+    return clean_tags[:MAX_MODEL_TAGS]
+
+
+def normalize_memory_type(value: object, *, fallback: str = "daily") -> str:
+    normalized = normalize_slug(value, max_length=MAX_MEMORY_TYPE_LENGTH)
+    if normalized:
+        return normalized
+    fallback_type = normalize_slug(fallback, max_length=MAX_MEMORY_TYPE_LENGTH)
+    return fallback_type or "daily"
+
+
+def normalize_slug(value: object, *, max_length: int) -> str:
+    if not isinstance(value, str):
+        return ""
+    lowered = value.strip().lower()
+    if not lowered:
+        return ""
+    normalized = re.sub(r"[^a-z0-9_-]+", "-", lowered)
+    normalized = re.sub(r"-{2,}", "-", normalized).strip("-_")
+    if len(normalized) <= max_length:
+        return normalized
+    return normalized[:max_length].rstrip("-_")
+
+
+def repair_json_payload(payload: str) -> str:
+    return re.sub(r",\s*([}\]])", r"\1", payload)
+
+
+def clean_text_field(value: object, *, fallback: str, limit: int) -> str:
+    if isinstance(value, str):
+        text = " ".join(value.strip().split())
+    else:
+        text = ""
+    if not text:
+        text = fallback
+    if len(text) <= limit:
+        return text
+    return f"{text[: limit - 3].rstrip()}..."