omnemo 0.1.0__py3-none-any.whl

omnemo/__init__.py

@@ -0,0 +1,3 @@
+"""Omnemo — memory-only MCP server: save, recall, search, forget."""
+
+__version__ = "0.1.0.dev0"

omnemo/cli.py

@@ -0,0 +1,175 @@
+"""CLI: `omnemo serve` runs the MCP server; save/recall/search/forget are
+direct verbs for testing; `omnemo stats` is the stats-only digest source.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from datetime import datetime
+
+from . import __version__
+from .config import ConfigError, load_config, store_path
+from .embedder import make_embedder
+from .store import CorruptStoreError, EmbedderMismatchError, Store
+
+# Anything the store/config layer reports as a clean, named error.
+_KNOWN_ERRORS = (ConfigError, CorruptStoreError, EmbedderMismatchError)
+
+
+def _open_store() -> Store:
+    config = load_config()
+    embedder = make_embedder(config.embedder)
+    return Store(store_path(), embedder, config)
+
+
+def _fmt_time(ts: float | None) -> str:
+    if ts is None:
+        return "never"
+    return datetime.fromtimestamp(ts).strftime("%Y-%m-%d %H:%M:%S")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="omnemo", description="Memory-only MCP server."
+    )
+    parser.add_argument("--version", action="version", version=__version__)
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    sub.add_parser("serve", help="run the MCP server on stdio")
+
+    p_save = sub.add_parser("save", help="save one memory")
+    p_save.add_argument("text")
+    p_save.add_argument("--category", "-c", default=None)
+
+    p_recall = sub.add_parser("recall", help="recall memories by meaning")
+    p_recall.add_argument("query")
+    p_recall.add_argument("--limit", "-n", type=int, default=None)
+
+    p_search = sub.add_parser("search", help="search memories by substring")
+    p_search.add_argument("query")
+    p_search.add_argument("--limit", "-n", type=int, default=None)
+
+    p_forget = sub.add_parser("forget", help="permanently delete a memory by id")
+    p_forget.add_argument("id", type=int)
+
+    p_stats = sub.add_parser(
+        "stats", help="memory count, learned today, last recall"
+    )
+    p_stats.add_argument("--json", action="store_true", dest="as_json")
+
+    sub.add_parser("warm", help="pre-load the embedder (boot warm-up)")
+
+    sub.add_parser(
+        "setup",
+        help="install the Omarchy glove: skill, bar plugin, warm-up, connect",
+    )
+    sub.add_parser("connect", help="register the MCP server with every harness")
+    p_disc = sub.add_parser("disconnect", help="unregister from every harness")
+    p_disc.add_argument(
+        "--all-pieces", action="store_true",
+        help="also remove skill links, bar plugin, and warm-up unit",
+    )
+
+    args = parser.parse_args(argv)
+
+    if args.command in ("setup", "connect", "disconnect"):
+        from .omarchy import glove
+        from .omarchy.harnesses import connect_all, disconnect_all
+
+        if args.command == "setup":
+            lines, results = glove.setup()
+        elif args.command == "connect":
+            lines, results = [], connect_all()
+        elif getattr(args, "all_pieces", False):
+            lines, results = glove.teardown()
+        else:
+            lines, results = [], disconnect_all()
+        for line in lines:
+            print(line)
+        failed = False
+        for r in results:
+            mark = "ok " if r.ok else "FAIL"
+            detail = f" — {r.detail}" if r.detail else ""
+            print(f"[{mark}] {r.harness}: {r.action}{detail}")
+            failed = failed or not r.ok
+        return 1 if failed else 0
+
+    if args.command == "warm":
+        try:
+            config = load_config()
+            embedder = make_embedder(config.embedder)
+            embedder.embed(["omnemo warm-up"])
+        except _KNOWN_ERRORS as e:
+            print(f"error: {e}", file=sys.stderr)
+            return 1
+        print("embedder warm")
+        return 0
+
+    if args.command == "serve":
+        from .server import serve
+
+        try:
+            serve()
+        except _KNOWN_ERRORS as e:
+            print(f"error: {e}", file=sys.stderr)
+            return 1
+        return 0
+
+    try:
+        store = _open_store()
+    except _KNOWN_ERRORS as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+
+    try:
+        if args.command == "save":
+            try:
+                memory = store.save(args.text, args.category)
+            except ValueError as e:
+                print(f"error: {e}", file=sys.stderr)
+                return 1
+            print(f"saved #{memory.id} [{memory.category}]")
+
+        elif args.command == "recall":
+            results = store.recall(args.query, args.limit)
+            if not results:
+                print("no memories recalled")
+            for r in results:
+                print(
+                    f"#{r.memory.id} [{r.memory.category}] "
+                    f"score={r.score:.3f} sim={r.similarity:.3f}  {r.memory.text}"
+                )
+
+        elif args.command == "search":
+            memories = store.search(args.query, args.limit)
+            if not memories:
+                print("no matches")
+            for m in memories:
+                print(f"#{m.id} [{m.category}]  {m.text}")
+
+        elif args.command == "forget":
+            if store.forget(args.id):
+                print(f"forgot #{args.id}")
+            else:
+                print(f"error: no memory #{args.id}", file=sys.stderr)
+                return 1
+
+        elif args.command == "stats":
+            s = store.stats()
+            if args.as_json:
+                import json
+
+                print(json.dumps(s))
+            else:
+                print(f"memories:      {s['memory_count']}")
+                print(f"learned today: {s['learned_today']}")
+                print(f"last recall:   {_fmt_time(s['last_recall_at'])}")
+    finally:
+        store.close()
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

omnemo/config.py

@@ -0,0 +1,208 @@
+"""Configuration: exposed defaults, optionally overridden by a TOML file.
+
+Every ranking weight, threshold, and category parameter lives here — never
+hard-coded at the point of use — so recall can be tuned on real data
+without touching code.
+
+Config file: $XDG_CONFIG_HOME/omnemo/config.toml (default ~/.config/omnemo/).
+Missing file or missing keys fall back to the shipped defaults below.
+Invalid values fail at load time with a ConfigError naming the key —
+hand-edited TOML is the supported tuning surface, so it must never crash
+a verb with a raw traceback later.
+"""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+class ConfigError(Exception):
+    """config.toml contains an invalid value."""
+
+
+def config_path() -> Path:
+    base = os.environ.get("XDG_CONFIG_HOME") or str(Path.home() / ".config")
+    return Path(base) / "omnemo" / "config.toml"
+
+
+def data_dir() -> Path:
+    base = os.environ.get("XDG_DATA_HOME") or str(Path.home() / ".local" / "share")
+    return Path(base) / "omnemo"
+
+
+def store_path() -> Path:
+    return data_dir() / "store.db"
+
+
+@dataclass(frozen=True)
+class Category:
+    """Per-category ranking parameters.
+
+    importance: additive weight in the composite recall score (0..1).
+    half_life_multiplier: scales the base recency half-life — memories in
+    a category with multiplier 2.0 fade half as fast as the base rate.
+    """
+
+    importance: float
+    half_life_multiplier: float
+
+
+DEFAULT_CATEGORIES: dict[str, Category] = {
+    "fact": Category(importance=0.6, half_life_multiplier=4.0),
+    "decision": Category(importance=1.0, half_life_multiplier=6.0),
+    "preference": Category(importance=0.8, half_life_multiplier=8.0),
+    "incident": Category(importance=0.9, half_life_multiplier=2.0),
+    "transient": Category(importance=0.2, half_life_multiplier=0.25),
+}
+
+
+@dataclass(frozen=True)
+class Config:
+    # Embedder spec: "fastembed:<model-name>".
+    embedder: str = "fastembed:BAAI/bge-small-en-v1.5"
+
+    # Recall ranking — composite score:
+    #   score = weight_similarity * cosine_similarity
+    #         + weight_recency    * 0.5 ** (age_days / (base_half_life_days * category.half_life_multiplier))
+    #         + weight_importance * category.importance
+    #         + weight_recall_count * min(recall_count, recall_count_cap) / recall_count_cap
+    # Candidates below min_similarity are dropped before scoring.
+    min_similarity: float = 0.35
+    weight_similarity: float = 1.0
+    weight_recency: float = 0.25
+    weight_importance: float = 0.15
+    weight_recall_count: float = 0.10
+    base_half_life_days: float = 30.0
+    recall_count_cap: int = 10
+
+    default_category: str = "fact"
+    recall_limit: int = 5
+    search_limit: int = 20
+
+    # Parameters used for memories whose saved category is no longer in
+    # the config (removed or renamed): recall degrades, never crashes.
+    fallback_importance: float = 0.5
+    fallback_half_life_multiplier: float = 1.0
+
+    categories: dict[str, Category] = field(
+        default_factory=lambda: dict(DEFAULT_CATEGORIES)
+    )
+
+
+_SCALAR_TYPES: dict[str, type] = {
+    "embedder": str,
+    "min_similarity": float,
+    "weight_similarity": float,
+    "weight_recency": float,
+    "weight_importance": float,
+    "weight_recall_count": float,
+    "base_half_life_days": float,
+    "recall_count_cap": int,
+    "default_category": str,
+    "recall_limit": int,
+    "search_limit": int,
+    "fallback_importance": float,
+    "fallback_half_life_multiplier": float,
+}
+
+
+def _scalar(key: str, value: object) -> object:
+    expected = _SCALAR_TYPES[key]
+    is_bool = isinstance(value, bool)
+    if expected is float and isinstance(value, (int, float)) and not is_bool:
+        return float(value)
+    if expected is int and isinstance(value, int) and not is_bool:
+        return value
+    if expected is str and isinstance(value, str):
+        return value
+    kind = {float: "number", int: "integer", str: "string"}[expected]
+    raise ConfigError(f"{key} must be a {kind} (got {value!r})")
+
+
+def _number(name: str, value: object) -> float:
+    if isinstance(value, (int, float)) and not isinstance(value, bool):
+        return float(value)
+    raise ConfigError(f"{name} must be a number (got {value!r})")
+
+
+def load_config(path: Path | None = None) -> Config:
+    """Load config from TOML, merging over the shipped defaults.
+
+    Raises ConfigError with the offending key named for any invalid value.
+    """
+    path = path if path is not None else config_path()
+    if not path.exists():
+        return Config()
+
+    with open(path, "rb") as f:
+        raw = tomllib.load(f)
+
+    kwargs: dict = {k: _scalar(k, raw[k]) for k in _SCALAR_TYPES if k in raw}
+
+    defaults = Config()
+    # Base for categories new to this file that omit a field.
+    new_base = Category(
+        importance=kwargs.get("fallback_importance", defaults.fallback_importance),
+        half_life_multiplier=kwargs.get(
+            "fallback_half_life_multiplier", defaults.fallback_half_life_multiplier
+        ),
+    )
+
+    raw_categories = raw.get("categories", {})
+    if not isinstance(raw_categories, dict):
+        raise ConfigError(f"categories must be a table (got {raw_categories!r})")
+    categories = dict(DEFAULT_CATEGORIES)
+    for name, params in raw_categories.items():
+        if not isinstance(params, dict):
+            raise ConfigError(f"categories.{name} must be a table (got {params!r})")
+        base = categories.get(name, new_base)
+        categories[name] = Category(
+            importance=_number(
+                f"categories.{name}.importance",
+                params.get("importance", base.importance),
+            ),
+            half_life_multiplier=_number(
+                f"categories.{name}.half_life_multiplier",
+                params.get("half_life_multiplier", base.half_life_multiplier),
+            ),
+        )
+    kwargs["categories"] = categories
+
+    config = Config(**kwargs)
+    _validate(config)
+    return config
+
+
+def _validate(config: Config) -> None:
+    if config.base_half_life_days <= 0:
+        raise ConfigError(
+            f"base_half_life_days must be positive (got {config.base_half_life_days})"
+        )
+    if config.fallback_half_life_multiplier <= 0:
+        raise ConfigError(
+            "fallback_half_life_multiplier must be positive "
+            f"(got {config.fallback_half_life_multiplier})"
+        )
+    for name, cat in config.categories.items():
+        if cat.half_life_multiplier <= 0:
+            raise ConfigError(
+                f"categories.{name}.half_life_multiplier must be positive "
+                f"(got {cat.half_life_multiplier})"
+            )
+    if config.recall_count_cap < 1:
+        raise ConfigError(
+            f"recall_count_cap must be >= 1 (got {config.recall_count_cap})"
+        )
+    if config.recall_limit < 1:
+        raise ConfigError(f"recall_limit must be >= 1 (got {config.recall_limit})")
+    if config.search_limit < 1:
+        raise ConfigError(f"search_limit must be >= 1 (got {config.search_limit})")
+    if config.default_category not in config.categories:
+        known = ", ".join(sorted(config.categories))
+        raise ConfigError(
+            f"default_category {config.default_category!r} is not a "
+            f"configured category (known: {known})"
+        )

omnemo/embedder.py

@@ -0,0 +1,83 @@
+"""Embedders: local only, one per store.
+
+The store records which embedder produced its vectors and refuses to open
+under a different one — mixing embedders fragments the vector space and
+silently breaks recall.
+
+No provider API keys are ever read from the environment; embedding never
+leaves the machine (fastembed's one-time model download excepted).
+"""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+
+class Embedder(Protocol):
+    """A text embedder. `name` identifies it in store metadata; `dim` is the
+    vector length. Both must be stable for the life of a store."""
+
+    @property
+    def name(self) -> str: ...
+
+    @property
+    def dim(self) -> int: ...
+
+    def warm_up(self) -> None:
+        """Load the model and run one embedding so first real use is fast."""
+        ...
+
+    def embed(self, texts: list[str]) -> list[list[float]]: ...
+
+
+class FastEmbedEmbedder:
+    """Local ONNX embedder via the fastembed package.
+
+    The model is downloaded once to fastembed's cache on first use; after
+    that everything runs offline.
+    """
+
+    def __init__(self, model_name: str = "BAAI/bge-small-en-v1.5") -> None:
+        self._model_name = model_name
+        self._model = None
+        self._dim: int | None = None
+
+    @property
+    def name(self) -> str:
+        return f"fastembed:{self._model_name}"
+
+    @property
+    def dim(self) -> int:
+        if self._dim is None:
+            # Known models: read the dimension from fastembed's registry so
+            # opening a store (which checks it) never forces a model load.
+            from fastembed import TextEmbedding
+
+            for entry in TextEmbedding.list_supported_models():
+                if entry["model"] == self._model_name:
+                    self._dim = int(entry["dim"])
+                    break
+            else:
+                self.warm_up()
+        assert self._dim is not None
+        return self._dim
+
+    def warm_up(self) -> None:
+        if self._model is None:
+            from fastembed import TextEmbedding  # deferred: heavy import
+
+            self._model = TextEmbedding(model_name=self._model_name)
+            self._dim = len(next(iter(self._model.embed(["warm up"]))))
+
+    def embed(self, texts: list[str]) -> list[list[float]]:
+        self.warm_up()
+        assert self._model is not None
+        return [[float(x) for x in vec] for vec in self._model.embed(texts)]
+
+
+def make_embedder(spec: str) -> Embedder:
+    """Build an embedder from a config spec string:
+    "fastembed:<model>" — local ONNX model (the default)."""
+    if spec.startswith("fastembed:"):
+        return FastEmbedEmbedder(spec.removeprefix("fastembed:"))
+    raise ValueError(f"unknown embedder spec: {spec!r}")

omnemo/omarchy/__init__.py

@@ -0,0 +1 @@
+"""The Omarchy glove: harness registration, skill links, bar plugin, warm-up."""

omnemo/omarchy/assets/plugin/BarWidget.qml

@@ -0,0 +1,78 @@
+import QtQuick
+import Quickshell
+import Quickshell.Io
+import qs.Commons
+import qs.Ui
+
+// Omnemo bar widget: memory count and what the machine learned today,
+// read from `omnemo stats --json` once a minute (and on click).
+//
+// Degrades honestly: if the CLI is missing or errors, the widget shows
+// "mem ?" rather than a stale or invented number.
+BarWidget {
+  id: root
+  moduleName: "omnemo.memory"
+
+  property int memoryCount: -1
+  property int learnedToday: 0
+
+  readonly property string displayText: memoryCount < 0
+    ? "𝍇 ?"
+    : (learnedToday > 0
+        ? "𝍇 " + memoryCount + " +" + learnedToday
+        : "𝍇 " + memoryCount)
+
+  readonly property int refreshIntervalSec: 60
+
+  function refresh() {
+    if (!statsProcess.running) statsProcess.running = true
+  }
+
+  function applyStats(text) {
+    try {
+      var s = JSON.parse(text)
+      root.memoryCount = s.memory_count
+      root.learnedToday = s.learned_today
+    } catch (e) {
+      root.memoryCount = -1
+    }
+  }
+
+  implicitWidth: button.implicitWidth
+  implicitHeight: button.implicitHeight
+
+  Process {
+    id: statsProcess
+    // pipx puts omnemo in ~/.local/bin; the shell's PATH may not include it.
+    command: ["/bin/sh", "-c", "PATH=\"$HOME/.local/bin:$PATH\" exec omnemo stats --json"]
+    stdout: StdioCollector {
+      onStreamFinished: root.applyStats(text)
+    }
+    onExited: function(exitCode) {
+      if (exitCode !== 0) root.memoryCount = -1
+    }
+  }
+
+  Timer {
+    interval: root.refreshIntervalSec * 1000
+    running: true
+    repeat: true
+    triggeredOnStart: true
+    onTriggered: root.refresh()
+  }
+
+  WidgetButton {
+    id: button
+    anchors.fill: parent
+    bar: root.bar
+    text: root.vertical ? "𝍇" : root.displayText
+    labelVisible: true
+    hasVisualContent: text !== ""
+    horizontalMargin: 8.75
+    verticalPadding: 8.75
+
+    onPressed: function(b) {
+      root.refresh()
+    }
+  }
+}

omnemo/omarchy/assets/plugin/manifest.json

@@ -0,0 +1,20 @@
+{
+  "schemaVersion": 1,
+  "id": "omnemo.memory",
+  "name": "Omnemo Memory",
+  "version": "0.1.0",
+  "author": "Omnemo",
+  "description": "What your machine remembered: memory count and today's learning",
+  "kinds": [
+    "bar-widget"
+  ],
+  "entryPoints": {
+    "barWidget": "BarWidget.qml"
+  },
+  "barWidget": {
+    "displayName": "Omnemo Memory",
+    "description": "Memory count · learned today, from the shared agent memory store",
+    "category": "System",
+    "allowMultiple": false
+  }
+}

omnemo/omarchy/assets/skill/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: omnemo
+description: Shared memory for every agent on this machine. Use to RECALL relevant context before starting non-trivial work, and to SAVE decisions, lessons, and durable facts other sessions (or other agents) will need. One store, all harnesses — what Codex saves, Claude recalls.
+---
+
+# Omnemo — the machine's shared memory
+
+This box runs one memory store, shared by every agent harness on it. It is
+served over MCP as `omnemo` (tools: `save`, `recall`, `search`, `forget`).
+If the MCP tools are unavailable, the same verbs work from the shell:
+`omnemo save "..."`, `omnemo recall "..."`, `omnemo search "..."`,
+`omnemo forget <id>`, `omnemo stats`.
+
+## When to RECALL
+
+- Before starting non-trivial work on this machine — one `recall` with a
+  short description of the task. Cheap, often decisive.
+- When the user references past work ("like last time", "the usual way",
+  "what we decided about X").
+- Before diagnosing a crash or recurring error: recall the binary or error
+  first — this machine may have seen it before and stored the fix.
+
+Recall returns ranked matches (similarity + recency + importance). Treat
+results as leads, not gospel: they reflect what was true when saved.
+
+## When to SAVE — conservative by default
+
+Save things that would change a future session's answer:
+
+- **Decisions with a why** — "chose X over Y because Z".
+- **Lessons paid for** — a root cause found, a fix that worked, a trap hit.
+- **Durable facts about this machine or its people** — preferences the user
+  stated, quirks of the hardware, project conventions not written elsewhere.
+
+One memory = one fact, in one or two plain sentences, with enough context to
+stand alone months from now. Name concrete things (paths, versions, project
+names) — future recall queries will match on them.
+
+## Do NOT save (this list does the real work)
+
+Over-saving is the #1 recall killer: every junk memory competes with a good
+one in every future recall. Skip:
+
+- **Transient state** — "the build is currently failing", "server is up",
+  today's TODO. It will be false soon, and recalled anyway.
+- **One-off mentions** — a file you touched once, a command's routine output,
+  a value you looked up and used.
+- **Anything re-derivable** — code structure, git history, contents of
+  config files. The next agent can read those directly; the repo is not
+  going anywhere.
+- **Whole transcripts or long dumps** — save the conclusion, not the journey.
+- **Secrets** — never API keys, passwords, tokens, or private credentials.
+  If the fact is "where a credential lives", save the location, never the value.
+
+Rule of thumb: if you would not write it on a sticky note for a colleague
+taking over tomorrow, do not save it.
+
+## Crash memory
+
+When Omarchy hands you a crash to diagnose (`omarchy-agent-crash`), FIRST
+`recall` the crashing binary's name. If a prior crash of the same binary was
+saved, lead with what fixed it last time. After diagnosing a NEW crash to a
+root cause, save one memory: binary, symptom, root cause, fix.
+
+## Forget
+
+When the user says a saved fact is wrong or asks to remove it: `search` for
+it, confirm the id, `forget <id>`. Forget deletes — it does not archive.
+Tell the user what was deleted.

omnemo/omarchy/assets/systemd/omnemo-warm.service

@@ -0,0 +1,11 @@
+[Unit]
+Description=Omnemo embedder warm-up (pre-loads the local embedding model)
+
+[Service]
+Type=oneshot
+ExecStart=%h/.local/bin/omnemo warm
+# The model download on first ever run can take a while; be patient once.
+TimeoutStartSec=600
+
+[Install]
+WantedBy=default.target