commonmemo 0.0.1__py3-none-any.whl

commonmemo/__init__.py

@@ -0,0 +1,171 @@
+"""CommonMemo -- framework-neutral memory for agents and workflows.
+
+Four tiers behind one `Memory` handle, plus structured kinds (tool memory,
+world facts, feedback, negatives, resume points) kept beside them:
+
+- **Log**         -- everything that happened, in order, never edited (owned by CommonMemo)
+- **Working**     -- what the current conversation or run has in hand (owned by CommonMemo)
+- **Recaps**      -- short summaries of finished sessions (delegated to an engine)
+- **UserProfile** -- durable facts about one user (delegated to an engine)
+
+See docs/design.md for the full design.
+"""
+
+from __future__ import annotations
+
+TYPE_CHECKING = False  # not `from typing import TYPE_CHECKING`: importing typing costs 7 ms a hook (#92)
+
+if TYPE_CHECKING:
+    from .context import MemoryContext, MemoryPolicy
+    from .engines import Engine, Fact, LocalEngine, Recap
+    from .events import (
+        Checkpoint,
+        ExternalEvent,
+        Feedback,
+        Forgotten,
+        MemoryEvent,
+        Message,
+        Negative,
+        ProcedureEntry,
+        ProcedureFollowed,
+        ToolInvoked,
+        UserFact,
+        WorldFact,
+        event_from_dict,
+    )
+    from .environment import EnvironmentResult
+    from .facts import FactKey
+    from .ranking import EmbeddingRanker, KeywordRanker
+    from .history import Diff, History, MemoryView
+    from .extraction import ExtractedFact, Extractor, ModelExtractor
+    from .learning import Learner, ModelLearner
+    from .memory import Memory
+    from .procedures import TaskProcedures
+    from .reins import Alert, AlertPolicy, Budget, RevertResult
+    from .resume import ResumePoint, StepInDoubt, StepInProgress
+    from .runs import Run, current_run
+    from .session import Session, current_session
+    from .stores import SQLiteStore, Store
+    from .tool_memory import ToolProfile
+
+
+# Importing the package must stay cheap: a hook process imports `commonmemo.hookclient` and nothing
+# else (#92), so the public names load on first use (PEP 562).
+_EXPORTS = {
+    "MemoryContext": ".context",
+    "MemoryPolicy": ".context",
+    "Engine": ".engines",
+    "Fact": ".engines",
+    "LocalEngine": ".engines",
+    "Recap": ".engines",
+    "Checkpoint": ".events",
+    "ExternalEvent": ".events",
+    "Feedback": ".events",
+    "Forgotten": ".events",
+    "MemoryEvent": ".events",
+    "Message": ".events",
+    "Negative": ".events",
+    "ProcedureEntry": ".events",
+    "ProcedureFollowed": ".events",
+    "ToolInvoked": ".events",
+    "UserFact": ".events",
+    "WorldFact": ".events",
+    "event_from_dict": ".events",
+    "EnvironmentResult": ".environment",
+    "FactKey": ".facts",
+    "EmbeddingRanker": ".ranking",
+    "KeywordRanker": ".ranking",
+    "Diff": ".history",
+    "History": ".history",
+    "MemoryView": ".history",
+    "ExtractedFact": ".extraction",
+    "Extractor": ".extraction",
+    "ModelExtractor": ".extraction",
+    "Learner": ".learning",
+    "ModelLearner": ".learning",
+    "Memory": ".memory",
+    "TaskProcedures": ".procedures",
+    "Alert": ".reins",
+    "AlertPolicy": ".reins",
+    "Budget": ".reins",
+    "RevertResult": ".reins",
+    "ResumePoint": ".resume",
+    "StepInDoubt": ".resume",
+    "StepInProgress": ".resume",
+    "Run": ".runs",
+    "current_run": ".runs",
+    "Session": ".session",
+    "current_session": ".session",
+    "SQLiteStore": ".stores",
+    "Store": ".stores",
+    "ToolProfile": ".tool_memory",
+}
+
+
+def __getattr__(name: str):
+    module = _EXPORTS.get(name)
+    if module is None:
+        raise AttributeError(f"module 'commonmemo' has no attribute {name!r}")
+    from importlib import import_module
+
+    value = getattr(import_module(module, __name__), name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted(set(globals()) | set(_EXPORTS))
+
+
+__version__ = "0.0.1"
+
+__all__ = [
+    "Memory",
+    "Session",
+    "current_session",
+    "MemoryContext",
+    "MemoryPolicy",
+    "EnvironmentResult",
+    "FactKey",
+    "EmbeddingRanker",
+    "KeywordRanker",
+    "WorldFact",
+    "Feedback",
+    "Negative",
+    "Forgotten",
+    "Checkpoint",
+    "ProcedureEntry",
+    "ProcedureFollowed",
+    "TaskProcedures",
+    "ExtractedFact",
+    "Extractor",
+    "Learner",
+    "ModelExtractor",
+    "ModelLearner",
+    "ResumePoint",
+    "StepInDoubt",
+    "StepInProgress",
+    "ToolProfile",
+    "History",
+    "MemoryView",
+    "Diff",
+    "Run",
+    "Alert",
+    "AlertPolicy",
+    "Budget",
+    "RevertResult",
+    "current_run",
+    "MemoryEvent",
+    "Message",
+    "ToolInvoked",
+    "UserFact",
+    "ExternalEvent",
+    "event_from_dict",
+    "Engine",
+    "Recap",
+    "Fact",
+    "LocalEngine",
+    "Store",
+    "SQLiteStore",
+    "__version__",
+]

commonmemo/__main__.py

@@ -0,0 +1,7 @@
+"""`python -m commonmemo ...` is the `commonmemo` command (see cli.py)."""
+
+import sys
+
+from .cli import main
+
+sys.exit(main())

commonmemo/agent_tools.py

@@ -0,0 +1,240 @@
+"""Memory tools for agents -- the *pull* half of hybrid memory.
+
+`Memory.agent_tools(session)` returns plain, typed, documented functions
+bound to one session, so any framework that turns Python functions into
+tools can use them as they are (CommonADK requires exactly that shape).
+
+Reads go further than the push: `memory_recall` searches every kind with no
+relevance threshold. Writes are recorded with `source="agent"`, so what an
+agent wrote can always be told apart from what the user or the application
+stated -- and reviewed, or revoked.
+
+Every name starts with `memory_`, so the tools cannot collide with an
+agent's own.
+
+The tools are **synchronous**: not every framework awaits an async tool
+(CommonADK's Claude adapter calls tool functions directly). Engine search
+is async, so `memory_recall` runs it on a worker thread with its own event
+loop; an engine whose client is bound to the caller's loop (Graphiti's
+async Neo4j driver can be) falls back to the exact local index rather than
+failing the tool call.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import concurrent.futures
+import json
+from typing import TYPE_CHECKING, Any, Callable, Coroutine
+
+from .context import MemoryContext, world_line
+from .events import Checkpoint, Negative, UserFact
+from .ranking import rank
+
+if TYPE_CHECKING:
+    from .session import Session
+
+def run_sync(coro: Coroutine[Any, Any, Any]) -> Any:
+    """Run `coro` to completion from synchronous code, inside or outside a
+    running event loop."""
+    try:
+        asyncio.get_running_loop()
+    except RuntimeError:
+        return asyncio.run(coro)
+    with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
+        return pool.submit(asyncio.run, coro).result()
+
+
+def build_agent_tools(session: "Session", *, writes: bool = True) -> list[Callable[..., str]]:
+    """The memory tools for `session`. `writes=False` gives read-only
+    tools (recall only). The session then knows its agent can recall, so
+    its push says when it left things out."""
+    memory = session.memory
+    session.recall_tool = True
+
+    def memory_recall(query: str) -> str:
+        """Search long-term memory: past sessions, what was said in them,
+        facts about the user, known world facts, past feedback, lessons and
+        decisions. Use it when the request may
+        depend on something from an earlier conversation that is not in
+        front of you. Returns matching entries, best first, or a note that
+        nothing matched.
+
+        Args:
+            query: What to look for, in plain words.
+        """
+        try:
+            ctx = run_sync(session.context(query, policy=memory.policy_for_recall))
+        except Exception:  # noqa: BLE001 -- see module docstring: degrade to the local index
+            ctx = run_sync(session.context(query, policy=memory.policy_for_recall, local_only=True))
+        bar = memory.policy_for_recall.min_recall_score
+
+        def related(items: list, text: Callable[[Any], str]) -> list:
+            # Best first, by the memory's ranker: by meaning with an embedder (#21).
+            return run_sync(rank(memory.ranker, query, items, text, threshold=bar))[0]
+
+        found = MemoryContext(
+            facts=related(ctx.facts, lambda f: f"{f.key} {f.value}"),
+            world=related([*ctx.world, *ctx.world_turn], memory._world_text),
+            lessons=related(ctx.lessons, lambda item: item.line()),
+            learned=related(ctx.learned, lambda x: x.text),
+            recaps=ctx.recaps, said=ctx.said, policy=memory.policy, agent=session.agent,
+        )
+        decisions = (related(memory.decisions(user_id=session.user_id)[:50],
+                             lambda d: f"{d.goal} {d.chosen} {d.outcome}")[:5] if session.user_id is not None else [])
+        lines = []
+        lines += [f"[user] {f.key}: {f.value}" for f in found.facts]
+        lines += [f"[fact] {world_line(w)}" for w in found.world]
+        lines += [f"[feedback] {item.line()}" for item in found.lessons]
+        lines += [f"[lesson] {x.line()}" for x in found.learned]
+        lines += [f"[decision] {d.line()}" for d in decisions]
+        lines += [f"[past session] {ctx.recap_line(e)}" for e in found.recaps]
+        lines += [f"[said] {w.line()}" for w in found.said]
+        text = "\n".join(lines) if lines else "Nothing in memory matches that."
+        if writes and not session.closed:  # what the agent pulled, as a trace (#50); read-only tools record nothing
+            session._trace("recall", found, text, extra=tuple(
+                {"kind": "decision", "id": d.event_id, "source": "learned", "events": [d.event_id]} for d in decisions
+            ), query=query)
+        return text
+
+    def memory_get_procedure(task: str) -> str:
+        """How a type of task is done here: its templates (the shape of a good
+        result), rules, step-by-step procedures, and accepted examples. Use it
+        before doing one of the tasks listed below, or when memory pointed you
+        at it.
+
+        Args:
+            task: The task's name, as listed.
+        """
+        known = memory.tasks(user_id=session.user_id)
+        found = memory.procedures(task, user_id=session.user_id) if task else None
+        if not found:
+            listing = "\n".join(f"- {t}: {w}" if w else f"- {t}" for t, w in known.items())
+            head = f"No procedure for {task!r}. " if task else ""
+            return head + ("Known tasks:\n" + listing if known else "No procedures are recorded yet.")
+        found.how = "pulled"
+        text = found.full_text()
+        if writes and not session.closed:  # read-only tools record nothing
+            session._trace("pull", MemoryContext(procedure=found, policy=memory.policy, agent=session.agent), text)
+        return text
+
+    reads: list[Callable[..., str]] = [memory_recall]
+    tasks = memory.tasks(user_id=session.user_id)
+    if tasks:
+        # Only when there is something to get; the task names go where the
+        # model reads them, the tool's description.
+        head, _, args = (memory_get_procedure.__doc__ or "").partition("\n\n        Args:")
+        listing = "\n".join(f"        - {t}: {w}" if w else f"        - {t}" for t, w in list(tasks.items())[:40])
+        memory_get_procedure.__doc__ = f"{head}\n\n        Known tasks:\n{listing}\n\n        Args:{args}"
+        reads.append(memory_get_procedure)
+
+    if not writes:
+        return reads
+
+    def memory_remember(key: str, value: str) -> str:
+        """Save a durable fact about the current user for future sessions,
+        e.g. key "preferred_contact", value "email". Use it only for things
+        the user stated or clearly confirmed. A new value for the same key
+        replaces the old one.
+
+        Args:
+            key: Short snake_case name of the fact.
+            value: The fact itself.
+        """
+        if session.user_id is None:
+            return "Not saved: this session has no user to remember things about."
+        session.record(UserFact(key=key, value=value, source="agent"))
+        return f"Saved: {key} = {value}"
+
+    def memory_note_fact(key: str, value: str, valid_for_seconds: int = 0) -> str:
+        """Note a fact about the world or this project (not about the user)
+        for future sessions, e.g. key "refund_window", value "30 days".
+        Facts you note are proposals: only this user sees them until an
+        operator approves them, because a world fact is shown to every user.
+        Set valid_for_seconds for facts that go stale (prices, statuses);
+        0 means it does not expire.
+
+        Args:
+            key: Short snake_case name of the fact.
+            value: The fact itself.
+            valid_for_seconds: How long the fact stays true; 0 for no expiry.
+        """
+        event = session.learn(key, value, ttl=valid_for_seconds or None, source="agent")
+        if event.proposed:
+            why = f" Note: {event.note}." if event.note else ""
+            return f"Proposed fact (other users see it once an operator approves it): {key} = {value}.{why}"
+        return f"Saved fact: {key} = {value}"
+
+    if memory.fact_keys:
+        # List the registered keys where the model reads them: the tool's own
+        # description, so it reuses `refund_window` instead of inventing
+        # `refund_period`.
+        head, _, args = (memory_note_fact.__doc__ or "").partition("\n\n        Args:")
+        known = "\n".join(f"        - {line}" for line in memory.fact_keys.agent_lines())
+        memory_note_fact.__doc__ = f"{head}\n\n        Use one of these keys when it fits:\n{known}\n\n        Args:{args}"
+
+    def memory_avoid(statement: str, reason: str = "") -> str:
+        """Record something to never do again for this user (or, without a
+        user, for this agent), e.g. "suggest phone calls". Use it when the
+        user asks you to stop doing something.
+
+        Args:
+            statement: What to avoid, phrased as an action.
+            reason: Why, if the user said.
+        """
+        scope = f"user:{session.user_id}" if session.user_id else f"agent:{session.agent or 'default'}"
+        session.record(Negative(statement=statement, scope=scope, reason=reason or None, source="agent"))
+        return f"Will avoid: {statement}"
+
+    def memory_save_progress(note: str, data_json: str = "{}") -> str:
+        """Record progress on a long task so it can be resumed if this
+        session is interrupted: what is done and what comes next.
+
+        Args:
+            note: One line on where the work stands.
+            data_json: Optional JSON object with details needed to continue.
+        """
+        try:
+            data = json.loads(data_json) if data_json.strip() else {}
+        except ValueError:
+            data = {"raw": data_json}
+        if not isinstance(data, dict):
+            data = {"value": data}
+        session.record(Checkpoint(label=note, data=data))
+        return "Progress saved."
+
+    def memory_save_procedure(task: str, kind: str, name: str, body: str, use_when: str = "",
+                              for_everyone: bool = False) -> str:
+        """Save how a type of task is done, for next time: a "template" (the
+        shape of a good result), a "rule" it must follow, a "procedure" (its
+        steps, one numbered line each), or an "exemplar" (a result the user
+        accepted). By default it is this user's own way; for_everyone=True
+        proposes it for every user, and an operator approves it first.
+        Exemplars always stay with this user.
+
+        Args:
+            task: Short snake_case name of the task, e.g. "weekly_report".
+            kind: "template", "rule", "procedure" or "exemplar".
+            name: Short name of this entry, e.g. "default".
+            body: The template, rule, steps or example itself.
+            use_when: One line saying when it applies.
+            for_everyone: Propose it for every user instead of keeping it for this one.
+        """
+        if kind not in ("template", "rule", "procedure", "exemplar"):
+            return f"Not saved: kind must be template, rule, procedure or exemplar, not {kind!r}."
+        if kind == "exemplar":
+            if session.user_id is None:
+                return "Not saved: an exemplar belongs to a user, and this session has none."
+            event = session.save_exemplar(task, body, name=name, use_when=use_when, source="agent")
+        else:
+            # Without a user there is no "own way": it can only be a proposal.
+            mine = not for_everyone and session.user_id is not None
+            event = session.save_procedure(task, kind, name, body, use_when=use_when, for_user=mine, source="agent")
+        if event.proposed:
+            return f"Proposed {kind} {name!r} for {task} (other users get it once an operator approves it)."
+        return f"Saved {kind} {name!r} for {task} (this user's own)."
+
+    return [*reads, memory_remember, memory_note_fact, memory_avoid, memory_save_progress, memory_save_procedure]
+
+
+__all__ = ["build_agent_tools"]

commonmemo/cli.py

@@ -0,0 +1,158 @@
+"""The `commonmemo` command. Subcommands:
+
+    commonmemo mcp [options]                  # memory as an MCP server over stdio (mcp.py)
+    commonmemo hook --harness NAME [options]  # one harness hook event, JSON on stdin (hooks.py)
+    commonmemo setup NAME [options]           # print the hook config for a harness (hooks.py)
+    commonmemo show user ID | session ID      # what memory holds, read-only (views.py)
+    commonmemo trace SESSION [--why KEY]      # what each push gave the agent, and why (traces.py)
+    commonmemo inspect [--port N]             # the same, in a local read-only web page (inspector.py)
+
+They share the memory options below: a flag wins over its `COMMONMEMO_*`
+environment variable, which wins over the default.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:
+    import argparse
+
+    from .context import MemoryPolicy
+    from .memory import Memory
+
+DEFAULT_STORE = "sqlite:///.commonmemo/memory.db"
+
+
+def env_flag(name: str) -> bool:
+    return os.environ.get(name, "").strip().lower() in ("1", "true", "yes", "on")
+
+
+WINDOWS = "8"
+"""`MemoryPolicy.messages` and `recall_messages`, as the option default (a test keeps them equal)."""
+
+
+def memory_options(p: argparse.ArgumentParser, *, agent: Optional[str]) -> argparse.ArgumentParser:
+    """Add the options that pick the memory, user, agent and session."""
+    env = os.environ.get
+    p.add_argument("--store", default=env("COMMONMEMO_STORE", DEFAULT_STORE))
+    p.add_argument("--engine", default=env("COMMONMEMO_ENGINE", "local"))
+    p.add_argument("--project", default=env("COMMONMEMO_PROJECT"))
+    p.add_argument("--user", default=env("COMMONMEMO_USER"))
+    p.add_argument("--agent", default=env("COMMONMEMO_AGENT", agent))
+    p.add_argument("--session", default=env("COMMONMEMO_SESSION"))
+    p.add_argument("--read-only", action="store_true", default=env_flag("COMMONMEMO_READ_ONLY"))
+    p.add_argument("--messages", type=int, default=int(env("COMMONMEMO_MESSAGES", WINDOWS)),
+                   help="windows of the user's past messages to push with each turn (default 8; 0: none)")
+    p.add_argument("--recall-messages", type=int,
+                   default=int(env("COMMONMEMO_RECALL_MESSAGES", WINDOWS)),
+                   help="windows of past messages memory_recall returns (default 8; 0: none)")
+    p.add_argument("--message-dates", choices=("off", "stamp", "resolve"), default=env("COMMONMEMO_MESSAGE_DATES", "off"),
+                   help="what windows say about when: off, stamp (dated messages), resolve (also relative dates)")
+    return p
+
+
+def policy_from(args: argparse.Namespace) -> "MemoryPolicy":
+    """The memory policy the command line asks for."""
+    from .context import MemoryPolicy
+
+    return MemoryPolicy(messages=args.messages, recall_messages=args.recall_messages, message_dates=args.message_dates)
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    args_ = sys.argv[1:] if argv is None else argv
+    if args_[:1] == ["hook"] and ("--resident" in args_ or env_flag("COMMONMEMO_RESIDENT")):
+        from .hookclient import main as client_main  # imports almost nothing: that is the point (#92)
+
+        return client_main(args_[1:])
+    import argparse
+
+    parser = argparse.ArgumentParser(prog="commonmemo")
+    sub = parser.add_subparsers(dest="command", required=True)
+    sub.add_parser("mcp", help="serve memory to MCP clients over stdio", add_help=False)
+    sub.add_parser("hook", help="handle one harness hook event (JSON on stdin)", add_help=False)
+    sub.add_parser("setup", help="print the hook config for claude-code, codex or opencode", add_help=False)
+    sub.add_parser("show", help="show a user or a session, read-only", add_help=False)
+    sub.add_parser("trace", help="show a session's turn traces", add_help=False)
+    sub.add_parser("inspect", help="open a local read-only web inspector", add_help=False)
+    args, rest = parser.parse_known_args(argv)
+    if args.command == "mcp":
+        from .mcp import main as mcp_main
+
+        return mcp_main(rest)
+    if args.command in ("hook", "setup"):
+        from . import hooks
+
+        return hooks.main(rest) if args.command == "hook" else hooks.setup_main(rest)
+    if args.command == "inspect":
+        from .inspector import main as inspect_main
+
+        return inspect_main(rest)
+    return show_main(rest) if args.command == "show" else trace_main(rest)
+
+
+def _open(args: argparse.Namespace) -> "Memory":
+    from .memory import Memory
+
+    return Memory(args.store, args.engine, project=args.project, policy=policy_from(args))
+
+
+def show_main(argv: Optional[list[str]] = None) -> int:
+    from .agent_tools import run_sync
+    from .views import session_lines, session_view, user_lines, user_view
+
+    import argparse
+
+    p = argparse.ArgumentParser(prog="commonmemo show", description="Show what memory holds, read-only.")
+    p.add_argument("what", choices=("user", "session"))
+    p.add_argument("id")
+    args = memory_options(p, agent=None).parse_args(argv)
+    mem = _open(args)
+    try:
+        if args.what == "user":
+            lines = user_lines(user_view(mem, args.id))
+        else:
+            view = session_view(mem, args.id)
+            if view is None:
+                print(f"no session {args.id!r}", file=sys.stderr)
+                return 1
+            lines = session_lines(view)
+        print("\n".join(lines))
+        return 0
+    finally:
+        run_sync(mem.aclose())
+
+
+def trace_main(argv: Optional[list[str]] = None) -> int:
+    from .agent_tools import run_sync
+    from .views import session_lines, session_view
+
+    import argparse
+
+    p = argparse.ArgumentParser(prog="commonmemo trace", description="What each push gave the agent, and why.")
+    p.add_argument("session")
+    p.add_argument("--why", metavar="KEY", help="trace one pushed item (a fact key, world fact key or id) to its sources")
+    args = memory_options(p, agent=None).parse_args(argv)
+    mem = _open(args)
+    try:
+        if args.why:
+            found = mem.why(args.why, session_id=args.session)
+            if found is None:
+                print(f"{args.why!r} was never pushed in session {args.session!r}", file=sys.stderr)
+                return 1
+            print("\n".join(found.lines()))
+            return 0
+        view = session_view(mem, args.session)
+        if view is None:
+            print(f"no session {args.session!r}", file=sys.stderr)
+            return 1
+        print("\n".join(session_lines(view, traces_only=True)))
+        return 0
+    finally:
+        run_sync(mem.aclose())
+
+
+if __name__ == "__main__":
+    sys.exit(main())