vvz-agent-memory 1.7.46__tar.gz

vvz_agent_memory-1.7.46/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: vvz-agent-memory
+Version: 1.7.46
+Summary: Agent dialogue memory for the vvz prompt contract: AI Logger, with a local .agent-memory/ file store while the logger is unreachable
+Author-email: Vasiliy Zdanovskiy <vasilyvz@gmail.com>
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: ailogger-client>=0.1.17
+Requires-Dist: embed-client>=4.0.24
+
+# vvz-agent-memory
+
+`agent-memory` is how agents of a `file_access: local` project under the vvz prompt contract write
+and read their dialogue messages. It wraps the published `ailogger-client`:
+
+- while the AI Logger is reachable, every call goes to the logger;
+- while it is unreachable (connection refused, connect timeout, DNS or transport failure, twice),
+  a write goes to `.agent-memory/<session_id>/` in the project root;
+- `agent-memory import` later moves those messages into the logger with their original
+  `message_id` and time (`messages_import`, `occurred_at`), and moves the imported files to
+  `.agent-memory/.imported/`.
+
+The package version equals the contract version (`1.7.46` serves contract `v1.7.46`).
+
+## The file store
+
+One message is two files side by side; the name sorts by time (UTC):
+
+```
+.agent-memory/<session_id>/2026-10-01T13.57.45.123-<UUID4>.msg   the message (JSON, logger fields + relations)
+.agent-memory/<session_id>/2026-10-01T13.57.45.123-<UUID4>.emb   its vector: {message_id, model, dimension, embedding}
+```
+
+The vector comes from the fleet embedding service through `embed_client`, with the logger's own
+model (`BAAI/bge-m3`, 1024), so the closeness group works locally and survives the import. When the
+embedder is down too, the `.msg` is written alone and `agent-memory embed` fills the `.emb` later.
+
+Files are created once and never edited. There are no locks: the sequence number of a file message
+is the count of messages already in the session, and references are resolved by `message_id`.
+The directory must exist and be ignored by git (the prompt deployment does both); otherwise the
+store is unavailable and nothing is written.
+
+## Configuration
+
+One JSON document: `--config`, else `$AGENT_MEMORY_CONFIG`, else
+`~/.config/vvz-agent-memory/config.json`. Sections `ailogger_client`, `embedding_client` (the fleet
+client shape: `protocol`, `server.host/port`, `client.timeout`, `ssl.cert/key/ca/check_hostname`,
+`auth.token/token_header`) and `embedding_model` (`model`, `dimension`). Relative paths resolve
+against the document's directory.
+
+```
+agent-memory config generate --output ~/.config/vvz-agent-memory/config.json \
+  --logger-host 192.168.254.26 --embed-host 192.168.254.26 \
+  --logger-cert client.crt --logger-key client.key --logger-ca ca.crt
+agent-memory config validate
+```
+
+## Commands
+
+Every command prints one JSON object: `{"success": true, "store": "logger|file|both", "data": …}`
+in the logger's own data shape, or `{"success": false, "error": {"code", "message"}}`.
+`--store auto|logger|file` (default `auto`) selects the side.
+
+| Command | Logger call | File store |
+|---|---|---|
+| `write` | `append_message` | new `.msg` + `.emb` |
+| `read --session-id --message-id [--sequence-number]` | `messages_read` block 1 (`message_get` finds the number) | the file ending in the id |
+| `preview --session-id --sender-identity` | `messages_read` mode preview | files of that sender; both sides merged |
+| `working-set --session-id (--anchor-message-id \| --anchor-text)` | `working_set` | last N up to the anchor + top M by cosine |
+| `relations --session-id` | `relations_read` | relations of the files; both sides merged |
+| `embed [--session-id]` | — | missing `.emb` files |
+| `import [--session-id] [--batch-size] [--keep]` | `messages_import` | moved to `.imported/` after success |
+| `config generate \| validate` | — | — |
+
+Exit codes: 0 success; 1 logger refused or failed (or an import item failed); 2 usage; 3 file store
+unavailable; 4 logger unreachable with no fallback; 5 not found; 6 configuration invalid;
+7 embedding unavailable where a vector is required.
+
+## Verification
+
+`python -m pipeline` in this directory runs every check against the live logger and embedder;
+`python -m pipeline <name>` runs one; `python -m pipeline --list` lists them.

vvz_agent_memory-1.7.46/README.md

@@ -0,0 +1,72 @@
+# vvz-agent-memory
+
+`agent-memory` is how agents of a `file_access: local` project under the vvz prompt contract write
+and read their dialogue messages. It wraps the published `ailogger-client`:
+
+- while the AI Logger is reachable, every call goes to the logger;
+- while it is unreachable (connection refused, connect timeout, DNS or transport failure, twice),
+  a write goes to `.agent-memory/<session_id>/` in the project root;
+- `agent-memory import` later moves those messages into the logger with their original
+  `message_id` and time (`messages_import`, `occurred_at`), and moves the imported files to
+  `.agent-memory/.imported/`.
+
+The package version equals the contract version (`1.7.46` serves contract `v1.7.46`).
+
+## The file store
+
+One message is two files side by side; the name sorts by time (UTC):
+
+```
+.agent-memory/<session_id>/2026-10-01T13.57.45.123-<UUID4>.msg   the message (JSON, logger fields + relations)
+.agent-memory/<session_id>/2026-10-01T13.57.45.123-<UUID4>.emb   its vector: {message_id, model, dimension, embedding}
+```
+
+The vector comes from the fleet embedding service through `embed_client`, with the logger's own
+model (`BAAI/bge-m3`, 1024), so the closeness group works locally and survives the import. When the
+embedder is down too, the `.msg` is written alone and `agent-memory embed` fills the `.emb` later.
+
+Files are created once and never edited. There are no locks: the sequence number of a file message
+is the count of messages already in the session, and references are resolved by `message_id`.
+The directory must exist and be ignored by git (the prompt deployment does both); otherwise the
+store is unavailable and nothing is written.
+
+## Configuration
+
+One JSON document: `--config`, else `$AGENT_MEMORY_CONFIG`, else
+`~/.config/vvz-agent-memory/config.json`. Sections `ailogger_client`, `embedding_client` (the fleet
+client shape: `protocol`, `server.host/port`, `client.timeout`, `ssl.cert/key/ca/check_hostname`,
+`auth.token/token_header`) and `embedding_model` (`model`, `dimension`). Relative paths resolve
+against the document's directory.
+
+```
+agent-memory config generate --output ~/.config/vvz-agent-memory/config.json \
+  --logger-host 192.168.254.26 --embed-host 192.168.254.26 \
+  --logger-cert client.crt --logger-key client.key --logger-ca ca.crt
+agent-memory config validate
+```
+
+## Commands
+
+Every command prints one JSON object: `{"success": true, "store": "logger|file|both", "data": …}`
+in the logger's own data shape, or `{"success": false, "error": {"code", "message"}}`.
+`--store auto|logger|file` (default `auto`) selects the side.
+
+| Command | Logger call | File store |
+|---|---|---|
+| `write` | `append_message` | new `.msg` + `.emb` |
+| `read --session-id --message-id [--sequence-number]` | `messages_read` block 1 (`message_get` finds the number) | the file ending in the id |
+| `preview --session-id --sender-identity` | `messages_read` mode preview | files of that sender; both sides merged |
+| `working-set --session-id (--anchor-message-id \| --anchor-text)` | `working_set` | last N up to the anchor + top M by cosine |
+| `relations --session-id` | `relations_read` | relations of the files; both sides merged |
+| `embed [--session-id]` | — | missing `.emb` files |
+| `import [--session-id] [--batch-size] [--keep]` | `messages_import` | moved to `.imported/` after success |
+| `config generate \| validate` | — | — |
+
+Exit codes: 0 success; 1 logger refused or failed (or an import item failed); 2 usage; 3 file store
+unavailable; 4 logger unreachable with no fallback; 5 not found; 6 configuration invalid;
+7 embedding unavailable where a vector is required.
+
+## Verification
+
+`python -m pipeline` in this directory runs every check against the live logger and embedder;
+`python -m pipeline <name>` runs one; `python -m pipeline --list` lists them.

vvz_agent_memory-1.7.46/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vvz-agent-memory"
+dynamic = ["version"]
+description = "Agent dialogue memory for the vvz prompt contract: AI Logger, with a local .agent-memory/ file store while the logger is unreachable"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "Vasiliy Zdanovskiy", email = "vasilyvz@gmail.com" }]
+dependencies = [
+    "ailogger-client>=0.1.17",
+    "embed-client>=4.0.24",
+]
+
+[project.scripts]
+agent-memory = "vvz_agent_memory.cli:main"
+
+[tool.setuptools]
+packages = ["vvz_agent_memory"]
+
+[tool.setuptools.dynamic]
+version = { attr = "vvz_agent_memory.__version__" }

vvz_agent_memory-1.7.46/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vvz_agent_memory-1.7.46/vvz_agent_memory/__init__.py

@@ -0,0 +1,12 @@
+"""vvz-agent-memory — the agent-memory CLI of the prompt-factory contract.
+
+Agents of a `file_access: local` project write and read their dialogue messages
+through this tool. It is a wrapper over `ailogger-client`: while the AI Logger is
+reachable every call goes to it; while it is not, messages are kept in
+`.agent-memory/<session_id>/` as `.msg` + `.emb` file pairs and are later moved
+into the logger with their original identity and time by `agent-memory import`.
+
+The package version equals the contract version it serves.
+"""
+
+__version__ = "1.7.46"

vvz_agent_memory-1.7.46/vvz_agent_memory/cli.py

@@ -0,0 +1,304 @@
+"""`agent-memory` — the command line.
+
+Every command prints exactly one JSON object on stdout:
+``{"success": true, "store": ..., "data": ...}`` or ``{"success": false, "error": {"code", "message"}}``.
+
+Exit codes: 0 success; 1 the logger refused or failed; 2 usage; 3 file store unavailable;
+4 logger unreachable (and no fallback); 5 not found; 6 configuration invalid;
+7 embedding service unavailable where a vector is required.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import sys
+import uuid
+from pathlib import Path
+from typing import Any
+
+from . import __version__, config as cfg
+from .filestore import FileStore, FileStoreUnavailable, project_root
+from .logger import LoggerFailure, LoggerUnreachable
+from .memory import Memory, NotFound, Unavailable
+
+KINDS = ("human", "model", "tool", "system")
+RELATION_KINDS = ("reply", "influence", "tool_result")
+EXIT = {"LOGGER_FAILURE": 1, "USAGE": 2, "FILE_STORE_UNAVAILABLE": 3, "LOGGER_UNREACHABLE": 4,
+        "NOT_FOUND": 5, "CONFIG_INVALID": 6, "EMBEDDING_UNAVAILABLE": 7}
+
+
+def _uuid4(value: str) -> str:
+    try:
+        parsed = uuid.UUID(value)
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError(f"not a UUID: {value!r}") from exc
+    if parsed.version != 4 or str(parsed) != value.lower():
+        raise argparse.ArgumentTypeError(f"not a canonical UUID4: {value!r}")
+    return str(parsed)
+
+
+def _relation(value: str) -> dict[str, str]:
+    kind, _, target = value.partition(":")
+    if kind not in RELATION_KINDS:
+        raise argparse.ArgumentTypeError(f"relation kind must be one of {list(RELATION_KINDS)}: {value!r}")
+    return {"to_message_id": _uuid4(target), "kind": kind}
+
+
+def _attributes(value: str) -> dict[str, Any]:
+    try:
+        parsed = json.loads(value)
+    except json.JSONDecodeError as exc:
+        raise argparse.ArgumentTypeError(f"--attributes is not JSON: {exc}") from exc
+    if not isinstance(parsed, dict):
+        raise argparse.ArgumentTypeError("--attributes must be a JSON object")
+    return parsed
+
+
+def _non_negative(value: str) -> int:
+    number = int(value)
+    if number < 0:
+        raise argparse.ArgumentTypeError("must be >= 0")
+    return number
+
+
+def _positive(value: str) -> int:
+    number = int(value)
+    if number <= 0:
+        raise argparse.ArgumentTypeError("must be > 0")
+    return number
+
+
+def _batch(value: str) -> int:
+    number = _positive(value)
+    if number > 1000:
+        raise argparse.ArgumentTypeError("the logger imports at most 1000 messages per call")
+    return number
+
+
+def _bool(value: str) -> bool:
+    if value.lower() in ("true", "yes", "1"):
+        return True
+    if value.lower() in ("false", "no", "0"):
+        return False
+    raise argparse.ArgumentTypeError("expected true or false")
+
+
+def _global_options(parser: argparse.ArgumentParser, suppress: bool) -> None:
+    """The same options before and after the subcommand; the subcommand's copy only overrides when given."""
+
+    def default(value: Any) -> Any:
+        return argparse.SUPPRESS if suppress else value
+
+    parser.add_argument("--config", default=default(None),
+                        help=f"configuration document (default ${cfg.ENV_VAR} or {cfg.DEFAULT_PATH})")
+    parser.add_argument("--root", default=default(None),
+                        help="project root holding .agent-memory/ (default: the git top level of the cwd)")
+    parser.add_argument("--store", choices=("auto", "logger", "file"), default=default("auto"),
+                        help="auto (default): logger, file store only while the logger is unreachable")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="agent-memory",
+        description="Agent dialogue memory: AI Logger, with the .agent-memory/ file store while it is unreachable.",
+    )
+    parser.add_argument("--version", action="version", version=f"agent-memory {__version__}")
+    _global_options(parser, suppress=False)
+    common = argparse.ArgumentParser(add_help=False)
+    _global_options(common, suppress=True)
+
+    class _Sub(argparse._SubParsersAction):  # every subcommand also takes the global options
+        def add_parser(self, name: str, **kwargs: Any) -> argparse.ArgumentParser:
+            kwargs.setdefault("parents", [common])
+            return super().add_parser(name, **kwargs)
+
+    parser.register("action", "parsers", _Sub)
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    w = sub.add_parser("write", help="append one message (append_message)")
+    w.add_argument("--session-id", required=True, type=_uuid4)
+    text = w.add_mutually_exclusive_group(required=True)
+    text.add_argument("--text")
+    text.add_argument("--text-file", help="file holding the text; '-' reads stdin")
+    w.add_argument("--sender-kind", required=True, choices=KINDS)
+    w.add_argument("--sender-identity", required=True)
+    w.add_argument("--receiver-kind", required=True, choices=KINDS)
+    w.add_argument("--receiver-identity", required=True)
+    w.add_argument("--reply-to", type=_uuid4, action="append", default=[], metavar="MESSAGE_ID",
+                   help="a reply relation to this message (repeatable)")
+    w.add_argument("--relation", type=_relation, action="append", default=[], metavar="KIND:MESSAGE_ID",
+                   help=f"a relation, kind one of {list(RELATION_KINDS)} (repeatable)")
+    w.add_argument("--attributes", type=_attributes, help="free-form JSON object")
+    w.add_argument("--priority", type=_non_negative)
+    w.add_argument("--corrects", type=_uuid4, metavar="MESSAGE_ID", help="the message this one corrects")
+    w.add_argument("--message-id", type=_uuid4, help="identifier to accept the message under (a retry)")
+
+    r = sub.add_parser("read", help="read one referenced message")
+    r.add_argument("--session-id", required=True, type=_uuid4)
+    r.add_argument("--message-id", required=True, type=_uuid4)
+    r.add_argument("--sequence-number", type=_non_negative)
+
+    p = sub.add_parser("preview", help="messages of one sender, one character of text each")
+    p.add_argument("--session-id", required=True, type=_uuid4)
+    p.add_argument("--sender-identity", required=True)
+    p.add_argument("--page-size", type=_positive, default=100)
+
+    ws = sub.add_parser("working-set", help="recent and closest messages around an anchor")
+    ws.add_argument("--session-id", required=True, type=_uuid4)
+    anchor = ws.add_mutually_exclusive_group(required=True)
+    anchor.add_argument("--anchor-message-id", type=_uuid4)
+    anchor.add_argument("--anchor-text")
+    ws.add_argument("--recency-count", type=_non_negative, default=10)
+    ws.add_argument("--similarity-count", type=_non_negative, default=10)
+
+    rel = sub.add_parser("relations", help="declared relations of a session")
+    rel.add_argument("--session-id", required=True, type=_uuid4)
+
+    e = sub.add_parser("embed", help="compute the missing .emb files of the file store")
+    e.add_argument("--session-id", type=_uuid4, action="append", default=[])
+
+    i = sub.add_parser("import", help="move file-store messages into the logger with their ids and times")
+    i.add_argument("--session-id", type=_uuid4, action="append", default=[],
+                   help="session to import (repeatable; default: every session in the store)")
+    i.add_argument("--batch-size", type=_batch, default=500)
+    i.add_argument("--keep", action="store_true",
+                   help="leave imported files in place (default: move them to .agent-memory/.imported/)")
+
+    c = sub.add_parser("config", help="generate or validate the configuration document")
+    csub = c.add_subparsers(dest="config_command", required=True)
+    g = csub.add_parser("generate", help="write a configuration document; every setting has an argument")
+    g.add_argument("--output", required=True, help="path of the document to write")
+    g.add_argument("--force", action="store_true", help="overwrite an existing document")
+    for side, port in (("logger", 8008), ("embed", 8001)):
+        g.add_argument(f"--{side}-protocol", choices=cfg.PROTOCOLS, default="mtls")
+        g.add_argument(f"--{side}-host", required=True)
+        g.add_argument(f"--{side}-port", type=int, default=port)
+        g.add_argument(f"--{side}-timeout", type=float, default=cfg.DEFAULT_TIMEOUT)
+        g.add_argument(f"--{side}-cert")
+        g.add_argument(f"--{side}-key")
+        g.add_argument(f"--{side}-ca")
+        g.add_argument(f"--{side}-check-hostname", type=_bool)
+        g.add_argument(f"--{side}-token")
+        g.add_argument(f"--{side}-token-header")
+    g.add_argument("--embed-model", default="BAAI/bge-m3", help="must be the logger's embedding model")
+    g.add_argument("--embed-dimension", type=_positive, default=1024)
+    csub.add_parser("validate", help="validate the configuration document", parents=[common])
+    return parser
+
+
+def _emit(payload: dict[str, Any]) -> None:
+    json.dump(payload, sys.stdout, ensure_ascii=False, default=str)
+    sys.stdout.write("\n")
+
+
+def _fail(code: str, message: str, **extra: Any) -> int:
+    _emit({"success": False, "error": {"code": code, "message": message, **extra}})
+    return EXIT[code]
+
+
+def _config_command(args: argparse.Namespace) -> int:
+    if args.config_command == "generate":
+        out = Path(args.output).expanduser().resolve()
+        if out.exists() and not args.force:
+            return _fail("USAGE", f"{out} exists; pass --force to overwrite")
+        document = cfg.generate(args)
+        errors = cfg.validate(document, out.parent)
+        if errors:
+            return _fail("CONFIG_INVALID", "the generated document is invalid; nothing written", errors=errors)
+        out.parent.mkdir(parents=True, exist_ok=True)
+        out.write_text(json.dumps(document, indent=2) + "\n", encoding="utf-8")
+        _emit({"success": True, "data": {"path": str(out)}})
+        return 0
+    try:
+        loaded = cfg.load(args.config)
+    except cfg.ConfigProblem as exc:
+        return _fail("CONFIG_INVALID", "configuration document is invalid", errors=exc.errors)
+    _emit({"success": True, "data": {"path": str(loaded.path), "errors": []}})
+    return 0
+
+
+def _read_text(args: argparse.Namespace) -> str:
+    if args.text is not None:
+        return args.text
+    if args.text_file == "-":
+        return sys.stdin.read()
+    return Path(args.text_file).read_text(encoding="utf-8")
+
+
+async def _run(args: argparse.Namespace, memory: Memory) -> dict[str, Any]:
+    if args.command == "write":
+        relations = [{"to_message_id": m, "kind": "reply"} for m in args.reply_to] + args.relation
+        text = _read_text(args)
+        if not text:
+            raise ValueError("the text is empty")
+        return await memory.write(
+            session_id=args.session_id, text=text, sender_kind=args.sender_kind,
+            sender_identity=args.sender_identity, receiver_kind=args.receiver_kind,
+            receiver_identity=args.receiver_identity, priority=args.priority, message_id=args.message_id,
+            relations=relations, corrects_message_id=args.corrects, attributes=args.attributes,
+        )
+    if args.command == "read":
+        return await memory.read(session_id=args.session_id, message_id=args.message_id,
+                                 sequence_number=args.sequence_number)
+    if args.command == "preview":
+        return await memory.preview(session_id=args.session_id, sender_identity=args.sender_identity,
+                                    page_size=args.page_size)
+    if args.command == "working-set":
+        return await memory.working_set(
+            session_id=args.session_id, anchor_message_id=args.anchor_message_id, anchor_text=args.anchor_text,
+            recency_count=args.recency_count, similarity_count=args.similarity_count)
+    if args.command == "relations":
+        return await memory.relations(session_id=args.session_id)
+    if args.command == "embed":
+        return await memory.embed_missing(session_ids=args.session_id)
+    if args.command == "import":
+        return await memory.import_sessions(session_ids=args.session_id, batch_size=args.batch_size,
+                                            keep=args.keep)
+    raise AssertionError(args.command)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    if args.command == "config":
+        return _config_command(args)
+    try:
+        loaded = cfg.load(args.config)
+    except cfg.ConfigProblem as exc:
+        return _fail("CONFIG_INVALID", "configuration document is invalid", errors=exc.errors)
+    files: FileStore | None = None
+    problem: str | None = None
+    try:
+        files = FileStore.open(project_root(args.root))
+    except FileStoreUnavailable as exc:
+        problem = str(exc)
+    if args.store == "file" and files is None:
+        return _fail("FILE_STORE_UNAVAILABLE", problem or "file store unavailable")
+    if args.command in ("embed", "import") and files is None:
+        return _fail("FILE_STORE_UNAVAILABLE", problem or "file store unavailable")
+    try:
+        result = asyncio.run(_run(args, Memory(loaded, args.store, files, problem)))
+    except ValueError as exc:
+        return _fail("USAGE", str(exc))
+    except NotFound as exc:
+        return _fail("NOT_FOUND", str(exc))
+    except FileStoreUnavailable as exc:
+        return _fail("FILE_STORE_UNAVAILABLE", str(exc))
+    except LoggerUnreachable as exc:
+        return _fail("LOGGER_UNREACHABLE", str(exc))
+    except Unavailable as exc:
+        return _fail("LOGGER_UNREACHABLE", str(exc), sides=exc.reasons)
+    except LoggerFailure as exc:
+        return _fail("LOGGER_FAILURE", str(exc), logger_code=exc.code)
+    code = 0
+    if args.command == "import" and any(s["failed"] for s in result["data"]["sessions"]):
+        code = EXIT["LOGGER_FAILURE"]
+    if args.command == "embed" and result["data"]["failed"]:
+        code = EXIT["EMBEDDING_UNAVAILABLE"]
+    _emit({"success": code == 0, **result})
+    return code
+
+
+if __name__ == "__main__":
+    sys.exit(main())