power-loop 0.7.2__tar.gz → 0.8.0__tar.gz

{power_loop-0.7.2 → power_loop-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: power-loop
-Version: 0.7.2
+Version: 0.8.0
 Summary: Embeddable agent execution kernel — LLM loop, hooks, events, tools, dynamic sub-agents.
 Author-email: zhangran <zhangran24@126.com>
 License: MIT

{power_loop-0.7.2 → power_loop-0.8.0}/power_loop/__init__.py

@@ -22,7 +22,7 @@ Stability tiers
 无版本承诺，可随时变更或删除。
 """
 
-__version__ = "0.7.2"
+__version__ = "0.8.0"
 
 from power_loop.agent.follow_up import FollowUpQueued
 from power_loop.agent.sink import MessageSink, NullSink, SQLiteSink
@@ -124,6 +124,13 @@ from power_loop.runtime.exec_backend import (
 )
 from power_loop.runtime.human_input import HumanInputRequired, request_user_input
 from power_loop.runtime.memory import MemoryProvider, MemorySnapshot, tag_as_memory
+from power_loop.runtime.notes import (
+    DEFAULT_NOTES_POLICY,
+    NotesFullError,
+    NotesPolicy,
+    SQLiteNoteMemory,
+    render_notes,
+)
 from power_loop.runtime.provider import (
     LLMProviderConfig,
     create_llm_service_from_config,
@@ -256,6 +263,11 @@ __all__ = [
 	"MemoryProvider",
 	"MemorySnapshot",
 	"tag_as_memory",
+	"NotesPolicy",
+	"NotesFullError",
+	"SQLiteNoteMemory",
+	"DEFAULT_NOTES_POLICY",
+	"render_notes",
 	"MemoryRecalledCtx",
 	"MemoryRecalledPayload",
 	"MemoryFailedPayload",

{power_loop-0.7.2 → power_loop-0.8.0}/power_loop/agent/types.py

@@ -6,6 +6,7 @@ from typing import TYPE_CHECKING, Any, Literal
 if TYPE_CHECKING:
     from power_loop.runtime.compact import Compactor
     from power_loop.runtime.memory import MemoryProvider
+    from power_loop.runtime.notes import NotesPolicy
     from power_loop.runtime.retry import LLMRetryPolicy
     from power_loop.runtime.runtime_state import RuntimeProjector
 
@@ -35,6 +36,9 @@ class AgentLoopConfig:
     retry_policy: LLMRetryPolicy | None = None
     memory: MemoryProvider | None = None
     memory_budget_tokens: int = 1500
+    # Bounds for the note_add/note_update/note_delete tools (agent-authored
+    # notes). None → DEFAULT_NOTES_POLICY. See power_loop.runtime.notes.
+    notes_policy: NotesPolicy | None = None
     skills_dir: str | None = None
     runtime_projectors: tuple[RuntimeProjector, ...] = field(default_factory=_default_runtime_projectors)
 

power_loop-0.8.0/power_loop/runtime/notes.py

@@ -0,0 +1,194 @@
+"""Agent-authored persistent notes ("self-managed memory").
+
+Complements :mod:`power_loop.runtime.memory`:
+
+* ``MemoryProvider`` is the *passive* seam — recall/remember at session
+  boundaries, the provider decides what to keep (summaries, facts, RAG).
+* Notes are *agent-driven* memory — the model itself decides mid-conversation
+  what is worth keeping, via the ``note_add`` / ``note_update`` /
+  ``note_delete`` default tools, persisted in the session store's ``notes``
+  table.
+
+The two meet in :class:`SQLiteNoteMemory`: a ``MemoryProvider`` whose
+``recall()`` renders the session's notes into one system message injected at
+every send (so the model always sees its own notes), and whose ``remember()``
+is a no-op (writes already happened through the tools, in real time).
+
+Capacity model
+--------------
+``NotesPolicy`` bounds everything. The default eviction mode is **reject**:
+when the table is full, ``note_add`` fails with an instructive error telling
+the model to delete or merge first. Silent loss is the worst failure mode for
+an agent's memory — being forced to curate beats quietly forgetting.
+``eviction="fifo"`` switches to queue semantics: the oldest unpinned note is
+dropped to make room (pinned notes are never auto-evicted).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal
+
+from power_loop.runtime.memory import LoopMessage
+from power_loop.runtime.session_store import NoteRow, SessionStore
+
+
+class NotesFullError(ValueError):
+    """note_add was refused because the session is at max_notes (reject mode)."""
+
+
+@dataclass(frozen=True)
+class NotesPolicy:
+    """Bounds for agent-authored notes.
+
+    max_notes        : per-session note count cap.
+    max_note_chars   : per-note content length cap (longer content is rejected,
+                       never truncated silently).
+    inject_max_chars : budget for the rendered recall message; oldest unpinned
+                       notes are elided first, and the rendering says how many
+                       were hidden so the model knows its memory view is partial.
+    eviction         : "reject" (default) — note_add errors when full;
+                       "fifo" — drop the oldest unpinned note to make room.
+    """
+
+    max_notes: int = 50
+    max_note_chars: int = 1000
+    inject_max_chars: int = 8000
+    eviction: Literal["reject", "fifo"] = "reject"
+
+
+DEFAULT_NOTES_POLICY = NotesPolicy()
+
+
+def add_note_checked(
+    store: SessionStore,
+    session_id: str,
+    content: str,
+    *,
+    pinned: bool = False,
+    policy: NotesPolicy = DEFAULT_NOTES_POLICY,
+) -> NoteRow:
+    """Policy-enforcing insert used by the ``note_add`` tool handler."""
+    content = content.strip()
+    if not content:
+        raise ValueError("note content is empty")
+    if len(content) > policy.max_note_chars:
+        raise ValueError(
+            f"note too long ({len(content)} chars > {policy.max_note_chars}); "
+            "keep notes short — store details in a file instead"
+        )
+    if store.count_notes(session_id) >= policy.max_notes:
+        if policy.eviction == "fifo":
+            for note in store.list_notes(session_id):
+                if not note.pinned:
+                    store.delete_note(session_id, note.note_id)
+                    break
+            else:
+                raise NotesFullError(
+                    f"notes are full ({policy.max_notes}) and all are pinned; "
+                    "unpin or delete (note_delete) before adding"
+                )
+        else:
+            raise NotesFullError(
+                f"notes are full ({policy.max_notes}); delete stale notes with "
+                "note_delete or merge related ones with note_update first"
+            )
+    return store.add_note(session_id, content, pinned=pinned)
+
+
+def update_note_checked(
+    store: SessionStore,
+    session_id: str,
+    note_id: int,
+    *,
+    content: str | None = None,
+    pinned: bool | None = None,
+    policy: NotesPolicy = DEFAULT_NOTES_POLICY,
+) -> None:
+    if content is not None:
+        content = content.strip()
+        if not content:
+            raise ValueError("note content is empty; use note_delete to remove a note")
+        if len(content) > policy.max_note_chars:
+            raise ValueError(
+                f"note too long ({len(content)} chars > {policy.max_note_chars})"
+            )
+    if content is None and pinned is None:
+        raise ValueError("nothing to update — pass content and/or pinned")
+    if not store.update_note(session_id, note_id, content=content, pinned=pinned):
+        raise ValueError(f"note #{note_id} does not exist")
+
+
+def render_notes(notes: list[NoteRow], *, policy: NotesPolicy = DEFAULT_NOTES_POLICY) -> str:
+    """Render notes as the text block injected at recall time.
+
+    Pinned notes always survive the character budget; unpinned notes are
+    elided oldest-first when over budget, with an explicit elision marker.
+    """
+    if not notes:
+        return ""
+    pinned = [n for n in notes if n.pinned]
+    unpinned = [n for n in notes if not n.pinned]
+
+    def line(n: NoteRow) -> str:
+        flag = " [pinned]" if n.pinned else ""
+        return f"#{n.note_id}{flag} {n.content}"
+
+    budget = policy.inject_max_chars
+    kept_unpinned: list[NoteRow] = []
+    used = sum(len(line(n)) + 1 for n in pinned)
+    # Keep the newest unpinned notes within budget (drop oldest first).
+    for n in reversed(unpinned):
+        cost = len(line(n)) + 1
+        if used + cost > budget:
+            break
+        kept_unpinned.append(n)
+        used += cost
+    kept_unpinned.reverse()
+    hidden = len(unpinned) - len(kept_unpinned)
+
+    shown = sorted(pinned + kept_unpinned, key=lambda n: n.note_id)
+    lines = [
+        "YOUR NOTES (persistent memory you maintain with note_add / note_update / "
+        "note_delete; survives context compaction):"
+    ]
+    lines.extend(line(n) for n in shown)
+    if hidden > 0:
+        lines.append(f"(… {hidden} older note(s) hidden by budget — consolidate or delete)")
+    return "\n".join(lines)
+
+
+class SQLiteNoteMemory:
+    """``MemoryProvider`` that injects the session's own notes every send.
+
+    ``remember()`` is a no-op: the notes table is mutated in real time by the
+    note tools, so there is nothing to persist at session end.
+
+    Pass the **same** :class:`SessionStore` the loop uses (or rely on the loop
+    sharing its store): ``StatefulAgentLoop(store=store,
+    config=AgentLoopConfig(memory=SQLiteNoteMemory(store)))``.
+    """
+
+    def __init__(
+        self, store: SessionStore, *, policy: NotesPolicy = DEFAULT_NOTES_POLICY
+    ) -> None:
+        self._store = store
+        self._policy = policy
+
+    async def recall(
+        self,
+        *,
+        messages: list[LoopMessage],
+        session_id: str | None,
+        budget_tokens: int = 1500,
+    ) -> list[LoopMessage]:
+        if session_id is None:
+            return []
+        notes = self._store.list_notes(session_id)
+        text = render_notes(notes, policy=self._policy)
+        if not text:
+            return []
+        return [{"role": "system", "name": "memory_notes", "content": text}]
+
+    async def remember(self, snapshot: Any) -> None:  # noqa: ARG002
+        return None

{power_loop-0.7.2 → power_loop-0.8.0}/power_loop/runtime/session_store.py

@@ -8,6 +8,7 @@ Owns the persistence layer for stateful agent loops:
   - session_state  : single-row per-session mutable state (next_seq, pending, …)
   - session_runtime_state : per-session JSON state for tool/runtime protocols
   - background_tasks : persisted background command task status
+  - notes            : agent-authored persistent notes (self-managed memory)
 
 The store is the **only** place that writes to disk. Callers (StatefulAgentLoop,
 the Sink that the pipeline drives, the subagent runtime) all go through here.
@@ -150,6 +151,16 @@ CREATE TABLE IF NOT EXISTS background_tasks (
 );
 CREATE INDEX IF NOT EXISTS idx_background_tasks_session_status
     ON background_tasks(session_id, status, updated_at);
+
+CREATE TABLE IF NOT EXISTS notes (
+    session_id        TEXT NOT NULL,
+    note_id           INTEGER NOT NULL,
+    content           TEXT NOT NULL,
+    pinned            INTEGER NOT NULL DEFAULT 0,
+    created_at        INTEGER NOT NULL,
+    updated_at        INTEGER NOT NULL,
+    PRIMARY KEY (session_id, note_id)
+);
 """
 
 
@@ -221,6 +232,19 @@ class BackgroundTaskRow:
     updated_at: int
 
 
+@dataclass
+class NoteRow:
+    """One agent-authored note. ``note_id`` is a short per-session integer so
+    the model can reference notes naturally ("update note 3")."""
+
+    session_id: str
+    note_id: int
+    content: str
+    pinned: bool
+    created_at: int
+    updated_at: int
+
+
 def _now_ms() -> int:
     return time.time_ns() // 1_000_000
 
@@ -389,6 +413,7 @@ class SessionStore:
         self._conn.execute("DELETE FROM usage_rounds WHERE session_id=?", (session_id,))
         self._conn.execute("DELETE FROM session_runtime_state WHERE session_id=?", (session_id,))
         self._conn.execute("DELETE FROM background_tasks WHERE session_id=?", (session_id,))
+        self._conn.execute("DELETE FROM notes WHERE session_id=?", (session_id,))
         self._conn.execute("DELETE FROM session_state WHERE session_id=?", (session_id,))
         cur = self._conn.execute("DELETE FROM sessions WHERE session_id=?", (session_id,))
         deleted += cur.rowcount
@@ -770,6 +795,92 @@ class SessionStore:
                 (now, session_id, *task_ids),
             )
 
+    # ── notes (agent-authored persistent memory) ──────────────────────────
+
+    def add_note(self, session_id: str, content: str, *, pinned: bool = False) -> NoteRow:
+        """Insert a note with the next per-session note_id and return it."""
+        now = _now_ms()
+        with self._lock, self._conn:
+            row = self._conn.execute(
+                "SELECT COALESCE(MAX(note_id), 0) + 1 AS nid FROM notes WHERE session_id=?",
+                (session_id,),
+            ).fetchone()
+            note_id = int(row["nid"])
+            self._conn.execute(
+                """
+                INSERT INTO notes (session_id, note_id, content, pinned, created_at, updated_at)
+                VALUES (?, ?, ?, ?, ?, ?)
+                """,
+                (session_id, note_id, content, 1 if pinned else 0, now, now),
+            )
+        return NoteRow(
+            session_id=session_id,
+            note_id=note_id,
+            content=content,
+            pinned=pinned,
+            created_at=now,
+            updated_at=now,
+        )
+
+    def update_note(
+        self,
+        session_id: str,
+        note_id: int,
+        *,
+        content: str | None = None,
+        pinned: bool | None = None,
+    ) -> bool:
+        """Update content and/or pinned flag. Returns False if the note doesn't exist."""
+        sets: list[str] = ["updated_at=?"]
+        params: list[Any] = [_now_ms()]
+        if content is not None:
+            sets.append("content=?")
+            params.append(content)
+        if pinned is not None:
+            sets.append("pinned=?")
+            params.append(1 if pinned else 0)
+        params.extend([session_id, note_id])
+        with self._lock, self._conn:
+            cur = self._conn.execute(
+                f"UPDATE notes SET {', '.join(sets)} WHERE session_id=? AND note_id=?",
+                params,
+            )
+        return cur.rowcount > 0
+
+    def delete_note(self, session_id: str, note_id: int) -> bool:
+        with self._lock, self._conn:
+            cur = self._conn.execute(
+                "DELETE FROM notes WHERE session_id=? AND note_id=?",
+                (session_id, note_id),
+            )
+        return cur.rowcount > 0
+
+    def list_notes(self, session_id: str) -> list[NoteRow]:
+        """All notes for a session in note_id (= creation) order."""
+        with self._lock:
+            rows = self._conn.execute(
+                "SELECT * FROM notes WHERE session_id=? ORDER BY note_id",
+                (session_id,),
+            ).fetchall()
+        return [
+            NoteRow(
+                session_id=r["session_id"],
+                note_id=int(r["note_id"]),
+                content=r["content"],
+                pinned=bool(r["pinned"]),
+                created_at=int(r["created_at"]),
+                updated_at=int(r["updated_at"]),
+            )
+            for r in rows
+        ]
+
+    def count_notes(self, session_id: str) -> int:
+        with self._lock:
+            row = self._conn.execute(
+                "SELECT COUNT(*) AS n FROM notes WHERE session_id=?", (session_id,)
+            ).fetchone()
+        return int(row["n"])
+
     # ── usage ─────────────────────────────────────────────────────────────
 
     def record_usage(

{power_loop-0.7.2 → power_loop-0.8.0}/power_loop/tools/default_manifest.py

@@ -185,6 +185,54 @@ DEFAULT_TOOL_DEFINITIONS: list[ToolDefinition] = [
         },
         required_params=("items",),
     ),
+    ToolDefinition(
+        name="note_add",
+        description=(
+            "Save a short persistent note to your own memory. Notes survive context compaction and are "
+            "shown back to you at the start of every turn. Use for durable facts, preferences, ongoing "
+            "task state — not for transcripts or long content (put those in files). When notes are full "
+            "you must delete or merge old ones first. Set pinned=true for notes that must never be "
+            "hidden or auto-evicted."
+        ),
+        input_schema={
+            "type": "object",
+            "properties": {
+                "content": {"type": "string", "description": "The note text. Keep it short and self-contained."},
+                "pinned": {"type": "boolean", "description": "Pinned notes are always visible and never auto-evicted. Default false."},
+            },
+            "required": ["content"],
+        },
+        required_params=("content",),
+    ),
+    ToolDefinition(
+        name="note_update",
+        description=(
+            "Rewrite or (un)pin one of your existing notes by its #id. Use to keep memory current "
+            "instead of piling up near-duplicates, and to merge related notes into one."
+        ),
+        input_schema={
+            "type": "object",
+            "properties": {
+                "note_id": {"type": "integer", "description": "The #id shown in YOUR NOTES."},
+                "content": {"type": "string", "description": "New text replacing the old content."},
+                "pinned": {"type": "boolean", "description": "Set or clear the pinned flag."},
+            },
+            "required": ["note_id"],
+        },
+        required_params=("note_id",),
+    ),
+    ToolDefinition(
+        name="note_delete",
+        description="Delete one of your notes by its #id when it is stale or no longer worth remembering.",
+        input_schema={
+            "type": "object",
+            "properties": {
+                "note_id": {"type": "integer", "description": "The #id shown in YOUR NOTES."},
+            },
+            "required": ["note_id"],
+        },
+        required_params=("note_id",),
+    ),
     ToolDefinition(
         name="background_run",
         description="Run a shell command in a private background worker (non-interactive).",

{power_loop-0.7.2 → power_loop-0.8.0}/power_loop/tools/default_tools.py

@@ -1135,6 +1135,49 @@ def run_todo(items: list[dict[str, Any]]) -> str:
     return get_ctx().todo.update(validated)
 
 
+def _notes_policy() -> Any:
+    """Resolve the active NotesPolicy: loop config override or the default."""
+    from power_loop.runtime.notes import DEFAULT_NOTES_POLICY
+
+    runtime_ctx = get_tool_runtime_context()
+    policy = getattr(runtime_ctx.config, "notes_policy", None) if runtime_ctx.config else None
+    return policy or DEFAULT_NOTES_POLICY
+
+
+def _notes_store_and_session() -> tuple[Any, str]:
+    store, sid = _current_store_and_session()
+    if store is None or sid is None:
+        raise RuntimeError("note tools need an active session (StatefulAgentLoop)")
+    return store, sid
+
+
+def run_note_add(content: str, pinned: bool = False) -> str:
+    from power_loop.runtime.notes import add_note_checked
+
+    store, sid = _notes_store_and_session()
+    policy = _notes_policy()
+    note = add_note_checked(store, sid, content, pinned=pinned, policy=policy)
+    count = store.count_notes(sid)
+    return f"noted as #{note.note_id} ({count}/{policy.max_notes} notes used)"
+
+
+def run_note_update(note_id: int, content: str | None = None, pinned: bool | None = None) -> str:
+    from power_loop.runtime.notes import update_note_checked
+
+    store, sid = _notes_store_and_session()
+    update_note_checked(
+        store, sid, int(note_id), content=content, pinned=pinned, policy=_notes_policy()
+    )
+    return f"note #{note_id} updated"
+
+
+def run_note_delete(note_id: int) -> str:
+    store, sid = _notes_store_and_session()
+    if not store.delete_note(sid, int(note_id)):
+        raise ValueError(f"note #{note_id} does not exist")
+    return f"note #{note_id} deleted ({store.count_notes(sid)} remaining)"
+
+
 DEFAULT_TOOL_HANDLERS: dict[str, Any] = {
     "bash": lambda **kw: run_bash(kw.get("command"), kw.get("restart", False), kw.get("timeout", 120)),
     "read_file": lambda **kw: run_read(kw["path"], kw.get("offset"), kw.get("limit")),
@@ -1158,6 +1201,11 @@ DEFAULT_TOOL_HANDLERS: dict[str, Any] = {
     ),
     "load_skill": lambda **kw: run_load_skill(kw["name"]),
     "todo": lambda **kw: run_todo(kw["items"]),
+    "note_add": lambda **kw: run_note_add(kw["content"], kw.get("pinned", False)),
+    "note_update": lambda **kw: run_note_update(
+        kw["note_id"], kw.get("content"), kw.get("pinned")
+    ),
+    "note_delete": lambda **kw: run_note_delete(kw["note_id"]),
     "background_run": lambda **kw: run_background(kw["command"]),
     "check_background": lambda **kw: check_background(kw.get("task_id")),
     "request_user_input": lambda **kw: request_user_input(

{power_loop-0.7.2 → power_loop-0.8.0}/power_loop.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: power-loop
-Version: 0.7.2
+Version: 0.8.0
 Summary: Embeddable agent execution kernel — LLM loop, hooks, events, tools, dynamic sub-agents.
 Author-email: zhangran <zhangran24@126.com>
 License: MIT

{power_loop-0.7.2 → power_loop-0.8.0}/power_loop.egg-info/SOURCES.txt

@@ -47,6 +47,7 @@ power_loop/runtime/env.py
 power_loop/runtime/exec_backend.py
 power_loop/runtime/human_input.py
 power_loop/runtime/memory.py
+power_loop/runtime/notes.py
 power_loop/runtime/provider.py
 power_loop/runtime/retry.py
 power_loop/runtime/runtime_state.py