groundmemory 0.2.4__py3-none-any.whl

groundmemory/__init__.py

@@ -0,0 +1,30 @@
+"""
+groundmemory — local-first, model-agnostic persistent memory for AI agents.
+
+Quick start
+-----------
+>>> from groundmemory import MemorySession
+>>> session = MemorySession.create("my_project")
+>>> session.sync()
+>>> print(session.bootstrap())          # inject into system prompt
+>>> result = session.execute_tool("memory_write", content="Alice loves Python.")
+>>> result = session.execute_tool("memory_search", query="Alice")
+>>> session.close()
+
+OpenAI adapter
+--------------
+>>> from groundmemory.adapters.openai import get_openai_tools, run_agent_loop
+
+Anthropic adapter
+-----------------
+>>> from groundmemory.adapters.anthropic import get_anthropic_tools, run_agent_loop
+"""
+from groundmemory.session import MemorySession
+from groundmemory.config import groundmemoryConfig
+
+__all__ = [
+    "MemorySession",
+    "groundmemoryConfig",
+]
+
+__version__ = "0.1.0"

groundmemory/adapters/__init__.py

@@ -0,0 +1 @@
+"""Adapters — format groundmemory tool schemas for specific LLM provider APIs."""

groundmemory/adapters/anthropic.py

@@ -0,0 +1,207 @@
+"""
+Anthropic adapter — converts groundmemory tool schemas into the format expected
+by the Anthropic Messages API (``tools`` parameter).
+
+Usage
+-----
+>>> import anthropic
+>>> from groundmemory.session import MemorySession
+>>> from groundmemory.adapters.anthropic import get_anthropic_tools, handle_tool_calls
+>>>
+>>> session = MemorySession.create("my_project")
+>>> client  = anthropic.Anthropic()
+>>>
+>>> response = client.messages.create(
+...     model="claude-opus-4-5",
+...     max_tokens=4096,
+...     system=session.bootstrap(),
+...     messages=[{"role": "user", "content": "What do you remember about Alice?"}],
+...     tools=get_anthropic_tools(),
+... )
+>>> messages, tool_results = handle_tool_calls(session, response)
+"""
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from groundmemory.tools import ALL_TOOLS
+
+
+# ---------------------------------------------------------------------------
+# Schema conversion
+# ---------------------------------------------------------------------------
+
+
+def _to_anthropic_tool(schema: dict) -> dict:
+    """Convert a single groundmemory SCHEMA dict to an Anthropic tool definition."""
+    return {
+        "name": schema["name"],
+        "description": schema["description"],
+        "input_schema": schema["parameters"],
+    }
+
+
+def get_anthropic_tools(names: list[str] | None = None) -> list[dict]:
+    """
+    Return Anthropic-formatted tool definitions for all (or a subset of) tools.
+
+    Parameters
+    ----------
+    names : list[str] | None
+        If provided, only include tools whose names are in this list.
+
+    Returns
+    -------
+    list[dict]
+        Ready to pass as ``tools=...`` in ``client.messages.create()``.
+    """
+    result = []
+    for schema, _ in ALL_TOOLS:
+        if names is None or schema["name"] in names:
+            result.append(_to_anthropic_tool(schema))
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Tool-call handling
+# ---------------------------------------------------------------------------
+
+
+def handle_tool_calls(
+    session: Any,
+    response: Any,
+) -> tuple[list[dict], list[dict]]:
+    """
+    Process all tool_use blocks in an Anthropic ``Message`` response.
+
+    Parameters
+    ----------
+    session  : MemorySession
+    response : anthropic.types.Message
+
+    Returns
+    -------
+    (assistant_turn, tool_result_turn)
+        Two message dicts ready to be appended to your messages list.
+        ``assistant_turn``   — the assistant message containing tool_use blocks.
+        ``tool_result_turn`` — a user message containing all tool_result blocks.
+
+    Example
+    -------
+    >>> asst, results = handle_tool_calls(session, response)
+    >>> messages += [asst, results]
+    """
+    # Build the assistant turn from the raw response content blocks
+    content_blocks = []
+    tool_use_blocks = []
+
+    for block in response.content:
+        block_dict = block.model_dump()
+        content_blocks.append(block_dict)
+        if block.type == "tool_use":
+            tool_use_blocks.append(block)
+
+    assistant_turn = {"role": "assistant", "content": content_blocks}
+
+    if not tool_use_blocks:
+        return assistant_turn, {}
+
+    # Execute each tool and collect results
+    tool_results = []
+    for block in tool_use_blocks:
+        kwargs = block.input if isinstance(block.input, dict) else {}
+        result = session.execute_tool(block.name, **kwargs)
+        tool_results.append(
+            {
+                "type": "tool_result",
+                "tool_use_id": block.id,
+                "content": json.dumps(result),
+            }
+        )
+
+    tool_result_turn = {"role": "user", "content": tool_results}
+    return assistant_turn, tool_result_turn
+
+
+def run_agent_loop(
+    session: Any,
+    client: Any,
+    messages: list[dict],
+    model: str = "claude-opus-4-5",
+    max_tokens: int = 4096,
+    system: str = "",
+    max_iterations: int = 10,
+    **create_kwargs: Any,
+) -> list[dict]:
+    """
+    Run a simple agentic loop that keeps calling the model until it stops
+    producing tool_use blocks (or ``max_iterations`` is reached).
+
+    Parameters
+    ----------
+    session        : MemorySession
+    client         : anthropic.Anthropic
+    messages       : list[dict]    Initial message list (user turns).
+    model          : str
+    max_tokens     : int
+    system         : str           System prompt (use session.bootstrap() here).
+    max_iterations : int           Safety cap.
+    **create_kwargs                Extra kwargs forwarded to ``client.messages.create``.
+
+    Returns
+    -------
+    list[dict]  Final message history.
+    """
+    from groundmemory.bootstrap.compaction import should_flush, get_compaction_prompts
+
+    tools = get_anthropic_tools()
+    # Auto-inject bootstrap if system is empty
+    if not system:
+        system = session.bootstrap()
+
+    compaction_cfg = session.config.compaction
+    _flushed = False  # only flush once per loop
+
+    for _ in range(max_iterations):
+        response = client.messages.create(
+            model=model,
+            max_tokens=max_tokens,
+            system=system,
+            messages=messages,
+            tools=tools,
+            **create_kwargs,
+        )
+
+        asst_turn, result_turn = handle_tool_calls(session, response)
+        messages.append(asst_turn)
+
+        # Check compaction threshold and inject a flush turn if needed
+        if not _flushed and compaction_cfg.enabled:
+            used = response.usage.input_tokens + response.usage.output_tokens
+            if should_flush(used, compaction_cfg):
+                prompts = get_compaction_prompts(compaction_cfg)
+                messages.append({"role": "user", "content": prompts["user"]})
+                # One dedicated flush turn — let the model write to memory
+                flush_response = client.messages.create(
+                    model=model,
+                    max_tokens=max_tokens,
+                    system=prompts["system"],
+                    messages=messages,
+                    tools=tools,
+                    **create_kwargs,
+                )
+                flush_asst, flush_results = handle_tool_calls(session, flush_response)
+                messages.append(flush_asst)
+                if flush_results:
+                    messages.append(flush_results)
+                _flushed = True
+
+        # Stop when the model finished without requesting tools
+        if response.stop_reason != "tool_use":
+            break
+
+        if result_turn:
+            messages.append(result_turn)
+
+    return messages

groundmemory/adapters/openai.py

@@ -0,0 +1,185 @@
+"""
+OpenAI adapter — converts groundmemory tool schemas into the format expected by
+the OpenAI Chat Completions ``tools`` parameter (function-calling API).
+
+Usage
+-----
+>>> from openai import OpenAI
+>>> from groundmemory.session import MemorySession
+>>> from groundmemory.adapters.openai import get_openai_tools, handle_tool_calls
+>>>
+>>> session = MemorySession.create("my_project")
+>>> client  = OpenAI()
+>>>
+>>> response = client.chat.completions.create(
+...     model="gpt-4o",
+...     messages=[{"role": "system", "content": session.bootstrap()},
+...               {"role": "user",   "content": "What do you remember about Alice?"}],
+...     tools=get_openai_tools(),
+... )
+>>> messages = handle_tool_calls(session, response, messages)
+"""
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from groundmemory.tools import ALL_TOOLS, TOOL_RUNNERS
+
+
+# ---------------------------------------------------------------------------
+# Schema conversion
+# ---------------------------------------------------------------------------
+
+
+def _to_openai_tool(schema: dict) -> dict:
+    """Convert a single groundmemory SCHEMA dict to an OpenAI tool definition."""
+    return {
+        "type": "function",
+        "function": {
+            "name": schema["name"],
+            "description": schema["description"],
+            "parameters": schema["parameters"],
+        },
+    }
+
+
+def get_openai_tools(names: list[str] | None = None) -> list[dict]:
+    """
+    Return OpenAI-formatted tool definitions for all (or a subset of) tools.
+
+    Parameters
+    ----------
+    names : list[str] | None
+        If provided, only include tools whose names are in this list.
+        Useful when you want to expose only a subset of memory tools.
+
+    Returns
+    -------
+    list[dict]
+        Ready to pass as ``tools=...`` in ``client.chat.completions.create()``.
+    """
+    result = []
+    for schema, _ in ALL_TOOLS:
+        if names is None or schema["name"] in names:
+            result.append(_to_openai_tool(schema))
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Tool-call handling
+# ---------------------------------------------------------------------------
+
+
+def handle_tool_calls(
+    session: Any,
+    response: Any,
+    messages: list[dict],
+) -> list[dict]:
+    """
+    Process all tool calls in an OpenAI ``ChatCompletion`` response.
+
+    Executes each tool call against *session*, appends the assistant message
+    and all tool result messages to *messages*, and returns the updated list.
+
+    Parameters
+    ----------
+    session  : MemorySession
+    response : openai.types.chat.ChatCompletion
+    messages : list[dict]   The current conversation message list (mutated in place).
+
+    Returns
+    -------
+    list[dict]  The same *messages* list with new entries appended.
+    """
+    choice = response.choices[0]
+    assistant_msg = choice.message
+
+    # Append the assistant turn (includes tool_calls)
+    messages.append(assistant_msg.model_dump(exclude_unset=True))
+
+    if not assistant_msg.tool_calls:
+        return messages
+
+    for tc in assistant_msg.tool_calls:
+        fn = tc.function
+        try:
+            kwargs = json.loads(fn.arguments) if fn.arguments else {}
+        except json.JSONDecodeError:
+            kwargs = {}
+
+        result = session.execute_tool(fn.name, **kwargs)
+        messages.append(
+            {
+                "role": "tool",
+                "tool_call_id": tc.id,
+                "content": json.dumps(result),
+            }
+        )
+
+    return messages
+
+
+def run_agent_loop(
+    session: Any,
+    client: Any,
+    messages: list[dict],
+    model: str = "gpt-4o",
+    max_iterations: int = 10,
+    **create_kwargs: Any,
+) -> list[dict]:
+    """
+    Run a simple agentic loop that keeps calling the model until it stops
+    producing tool calls (or ``max_iterations`` is reached).
+
+    Parameters
+    ----------
+    session        : MemorySession
+    client         : openai.OpenAI
+    messages       : list[dict]    Initial message list (system + user turns).
+    model          : str
+    max_iterations : int           Safety cap to prevent infinite loops.
+    **create_kwargs                Extra kwargs forwarded to ``client.chat.completions.create``.
+
+    Returns
+    -------
+    list[dict]  Final message history.
+    """
+    from groundmemory.bootstrap.compaction import should_flush, get_compaction_prompts
+
+    tools = get_openai_tools()
+    compaction_cfg = session.config.compaction
+    _flushed = False  # only flush once per loop
+
+    for _ in range(max_iterations):
+        response = client.chat.completions.create(
+            model=model,
+            messages=messages,
+            tools=tools,
+            **create_kwargs,
+        )
+        choice = response.choices[0]
+        messages = handle_tool_calls(session, response, messages)
+
+        # Check compaction threshold and inject a flush turn if needed
+        if not _flushed and compaction_cfg.enabled:
+            usage = response.usage
+            used = (usage.prompt_tokens or 0) + (usage.completion_tokens or 0)
+            if should_flush(used, compaction_cfg):
+                prompts = get_compaction_prompts(compaction_cfg)
+                messages.append({"role": "user", "content": prompts["user"]})
+                # One dedicated flush turn — let the model write to memory
+                flush_response = client.chat.completions.create(
+                    model=model,
+                    messages=[{"role": "system", "content": prompts["system"]}] + messages,
+                    tools=tools,
+                    **create_kwargs,
+                )
+                messages = handle_tool_calls(session, flush_response, messages)
+                _flushed = True
+
+        # Stop when the model is done calling tools
+        if choice.finish_reason != "tool_calls":
+            break
+
+    return messages

groundmemory/bootstrap/__init__.py

@@ -0,0 +1 @@
+"""Bootstrap package — system-prompt injection and compaction helpers."""

groundmemory/bootstrap/compaction.py

@@ -0,0 +1,77 @@
+"""
+Compaction helpers — detect when the context window is nearly full and
+provide prompts that instruct the agent to flush important information
+to memory before the session is compacted.
+"""
+from __future__ import annotations
+
+from groundmemory.config import CompactionConfig
+
+# ---------------------------------------------------------------------------
+# Flush detection
+# ---------------------------------------------------------------------------
+
+_DEFAULT_SYSTEM_PROMPT = """\
+You are about to run out of context window space. Before the session is \
+compacted, you MUST save all important information to long-term memory using \
+the memory_write tool. Focus on:
+
+1. Key facts, decisions, and outcomes from this session.
+2. Any new relationships between entities (use memory_relate).
+3. Updated user preferences or project state.
+4. Anything the user would want remembered in a future session.
+
+Write concisely — prefer bullet points. Do NOT include information that is \
+already recorded in previous memory entries unless it has changed.\
+"""
+
+_DEFAULT_USER_PROMPT = """\
+Please save a summary of our conversation so far to memory before we continue. \
+Use memory_write to store the key points, and memory_relate for any entity \
+relationships you have discovered.\
+"""
+
+
+def should_flush(
+    current_tokens: int,
+    cfg: CompactionConfig,
+    context_window: int | None = None,
+) -> bool:
+    """
+    Return True when the agent should flush memory before compaction.
+
+    Parameters
+    ----------
+    current_tokens : int
+        Tokens *consumed* so far in the current context window (i.e. counted
+        from zero, not tokens remaining at the end).
+    cfg            : CompactionConfig
+    context_window : int | None
+        Total token capacity of the model.  Defaults to
+        ``cfg.context_window_tokens`` when not supplied.
+
+    The flush fires when token usage reaches the lower of two limits::
+
+        soft limit : cfg.soft_threshold_tokens
+                     (absolute usage ceiling — fire no later than this)
+        hard limit : context_window - cfg.reserve_floor_tokens
+                     (always keep this many tokens free for the model's reply)
+    """
+    if not cfg.enabled:
+        return False
+
+    window = context_window if context_window is not None else cfg.context_window_tokens
+    hard_limit = window - cfg.reserve_floor_tokens
+    return current_tokens >= min(cfg.soft_threshold_tokens, hard_limit)
+
+
+def get_compaction_prompts(cfg: CompactionConfig) -> dict[str, str]:
+    """
+    Return ``{"system": str, "user": str}`` prompts for the pre-compaction flush.
+
+    Values come from the config when set, otherwise fall back to sensible defaults.
+    """
+    return {
+        "system": cfg.system_prompt or _DEFAULT_SYSTEM_PROMPT,
+        "user": cfg.user_prompt or _DEFAULT_USER_PROMPT,
+    }

groundmemory/bootstrap/injector.py

@@ -0,0 +1,149 @@
+"""
+Bootstrap injector — builds the system-prompt string that loads an agent's
+long-term memory context at the start of a session.
+
+Design goals
+------------
+* Respect BootstrapConfig.max_chars_per_file and max_total_chars so
+  the injection never blows the context window.
+* Warn (with a visible marker) when a file is truncated so the agent knows
+  it doesn't have the full picture.
+* Optionally include the relation graph and daily logs.
+"""
+from __future__ import annotations
+
+import datetime
+from pathlib import Path
+from typing import Sequence
+
+from groundmemory.config import BootstrapConfig
+from groundmemory.core.workspace import Workspace
+from groundmemory.core import storage, relations as _graph
+from groundmemory.core.index import MemoryIndex
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _read_capped(path: Path, max_chars: int) -> tuple[str, bool]:
+    """
+    Read *path* and return (text, truncated).
+
+    ``truncated`` is True when the file was longer than ``max_chars``.
+    """
+    if not path.exists():
+        return "", False
+    full = storage.read_file(path)
+    if len(full) <= max_chars:
+        return full, False
+    return full[:max_chars], True
+
+
+def _section(title: str, body: str, truncated: bool = False) -> str:
+    """Wrap *body* in a labelled Markdown block."""
+    marker = " [TRUNCATED — use memory_get to read the rest]" if truncated else ""
+    return f"### {title}{marker}\n\n{body}\n"
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def build_bootstrap_prompt(
+    workspace: Workspace,
+    cfg: BootstrapConfig,
+    index: MemoryIndex | None = None,
+) -> str:
+    """
+    Build the full memory-injection string for the system prompt.
+
+    Parameters
+    ----------
+    workspace : Workspace
+    cfg       : BootstrapConfig  (from groundmemoryConfig.bootstrap)
+    index     : MemoryIndex | None
+        Only needed when ``cfg.inject_relations`` is True and you want
+        relation data from SQLite rather than only from RELATIONS.md.
+
+    Returns
+    -------
+    str
+        Ready-to-prepend system prompt block (may be empty string).
+    """
+    sections: list[str] = []
+    total_chars = 0
+
+    def _add(title: str, path: Path | None, body: str | None = None) -> bool:
+        """Add a section, respecting the total char budget. Returns False if budget exhausted."""
+        nonlocal total_chars
+        remaining = cfg.max_total_chars - total_chars
+        if remaining <= 0:
+            return False
+
+        if body is None:
+            if path is None or not path.exists():
+                return True
+            raw, truncated = _read_capped(path, min(cfg.max_chars_per_file, remaining))
+            if not raw.strip():
+                return True
+            body_text = raw
+        else:
+            truncated = len(body) > cfg.max_chars_per_file
+            body_text = body[: cfg.max_chars_per_file] if truncated else body
+            if len(body_text) > remaining:
+                body_text = body_text[:remaining]
+                truncated = True
+
+        if not body_text.strip():
+            return True
+
+        sections.append(_section(title, body_text, truncated))
+        total_chars += len(body_text)
+        return total_chars < cfg.max_total_chars
+
+    # 1. Long-term memory (MEMORY.md)
+    if cfg.inject_long_term_memory:
+        _add("Long-Term Memory", workspace.memory_file)
+
+    # 2. User profile (USER.md)
+    if cfg.inject_user_profile:
+        _add("User Profile", workspace.user_file)
+
+    # 3. Agent roster (AGENTS.md)
+    if cfg.inject_agents:
+        _add("Agent Roster", workspace.agents_file)
+
+    # 4. Relation graph
+    if cfg.inject_relations:
+        if index is not None:
+            relations = _graph.get_relations(index)
+            if relations:
+                rel_md = _graph.format_relations_for_context(relations)
+                _add("Relation Graph", None, body=rel_md)
+        else:
+            _add("Relation Graph", workspace.relations_file)
+
+    # 5. Daily logs: today + yesterday
+    if cfg.inject_daily_logs:
+        today = datetime.date.today()
+        yesterday = today - datetime.timedelta(days=1)
+        for day in (yesterday, today):
+            day_path = workspace.daily_file(day)
+            label = f"Daily Log ({day.isoformat()})"
+            if not _add(label, day_path):
+                break  # budget exhausted
+
+    if not sections:
+        return ""
+
+    header = (
+        "<!-- groundmemory bootstrap start -->\n"
+        "## Your Memory Context\n\n"
+        "The following information was loaded from your long-term memory store. "
+        "Use it to maintain continuity across sessions.\n\n"
+    )
+    footer = "\n<!-- groundmemory bootstrap end -->"
+    return header + "\n".join(sections) + footer