openagent-framework 0.2.6__tar.gz → 0.2.7__tar.gz

{openagent_framework-0.2.6 → openagent_framework-0.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openagent-framework
-Version: 0.2.6
+Version: 0.2.7
 Summary: Simplified LLM agent framework with MCP, memory, and multi-channel support
 License-Expression: MIT
 Requires-Python: >=3.11
@@ -168,6 +168,29 @@ These are handled automatically by OpenAgent — you just write `openagent.yaml`
 
 ---
 
+## System prompt
+
+OpenAgent injects a **framework-level system prompt** in front of your
+user-defined `system_prompt` on every model call. It codifies guidelines
+that apply to every deployment:
+
+- How to use the memory vault (mcpvault tools, wikilinks, tags).
+- Prefer MCP tools over `shell_exec` and ad-hoc scripts.
+- Act autonomously under `permission_mode: bypass`; only stop for
+  ambiguous or irreversible actions.
+- Be concise; lead with the answer, not the reasoning.
+
+Your `system_prompt` in `openagent.yaml` should therefore stay **short
+and project-specific** — just identity and a pointer to the memory
+vault. Everything else (package names, host names, credentials,
+procedures) belongs as `.md` notes inside the vault, where the agent
+will find them via `search_notes`.
+
+The framework prompt source lives at `openagent/prompts.py:FRAMEWORK_SYSTEM_PROMPT`
+if you want to read or tweak the wording.
+
+---
+
 ## Memory
 
 OpenAgent's long-term memory is a plain **Obsidian-compatible markdown vault**. The agent reads and writes `.md` files directly via the [`mcpvault`](https://www.npmjs.com/package/@bitbonsai/mcpvault) MCP — no custom index, no full-text engine, no proprietary format. The files on disk *are* the database.

{openagent_framework-0.2.6 → openagent_framework-0.2.7}/docs/README.md

@@ -141,6 +141,29 @@ These are handled automatically by OpenAgent — you just write `openagent.yaml`
 
 ---
 
+## System prompt
+
+OpenAgent injects a **framework-level system prompt** in front of your
+user-defined `system_prompt` on every model call. It codifies guidelines
+that apply to every deployment:
+
+- How to use the memory vault (mcpvault tools, wikilinks, tags).
+- Prefer MCP tools over `shell_exec` and ad-hoc scripts.
+- Act autonomously under `permission_mode: bypass`; only stop for
+  ambiguous or irreversible actions.
+- Be concise; lead with the answer, not the reasoning.
+
+Your `system_prompt` in `openagent.yaml` should therefore stay **short
+and project-specific** — just identity and a pointer to the memory
+vault. Everything else (package names, host names, credentials,
+procedures) belongs as `.md` notes inside the vault, where the agent
+will find them via `search_notes`.
+
+The framework prompt source lives at `openagent/prompts.py:FRAMEWORK_SYSTEM_PROMPT`
+if you want to read or tweak the wording.
+
+---
+
 ## Memory
 
 OpenAgent's long-term memory is a plain **Obsidian-compatible markdown vault**. The agent reads and writes `.md` files directly via the [`mcpvault`](https://www.npmjs.com/package/@bitbonsai/mcpvault) MCP — no custom index, no full-text engine, no proprietary format. The files on disk *are* the database.

{openagent_framework-0.2.6 → openagent_framework-0.2.7}/openagent/__init__.py

@@ -1,5 +1,5 @@
 from openagent.agent import Agent
 from openagent.config import load_config
 
-__version__ = "0.2.6"
+__version__ = "0.2.7"
 __all__ = ["Agent", "load_config"]

{openagent_framework-0.2.6 → openagent_framework-0.2.7}/openagent/agent.py

@@ -8,6 +8,7 @@ from typing import Any, AsyncIterator, Callable, Awaitable
 from openagent.models.base import BaseModel, ModelResponse
 from openagent.memory.db import MemoryDB
 from openagent.mcp.client import MCPRegistry, MCPTools
+from openagent.prompts import FRAMEWORK_SYSTEM_PROMPT
 
 logger = logging.getLogger(__name__)
 
@@ -192,7 +193,9 @@ class Agent:
         """Inner run logic, wrapped by run() for crash protection."""
         await _status("Loading context...")
 
-        system = self.system_prompt
+        # Combine OpenAgent's framework-level guidelines with the user's
+        # project-specific system prompt from openagent.yaml.
+        system = self._combined_system_prompt()
 
         # Build messages
         if attachments:
@@ -244,6 +247,17 @@ class Agent:
 
         return response.content if response else "I wasn't able to complete the request."
 
+    def _combined_system_prompt(self) -> str:
+        """Prepend the framework-level prompt to the user's system prompt."""
+        user = (self.system_prompt or "").strip()
+        if not user:
+            return FRAMEWORK_SYSTEM_PROMPT
+        return (
+            FRAMEWORK_SYSTEM_PROMPT
+            + "\n\n── User-specific identity and project context ──\n\n"
+            + user
+        )
+
     async def stream_run(
         self,
         message: str,
@@ -256,7 +270,7 @@ class Agent:
 
         await self.initialize()
 
-        system = self.system_prompt
+        system = self._combined_system_prompt()
         messages: list[dict[str, Any]] = [{"role": "user", "content": message}]
 
         async for chunk in self.model.stream(messages, system=system):

openagent_framework-0.2.7/openagent/prompts.py

@@ -0,0 +1,81 @@
+"""Framework-level prompts injected into every OpenAgent conversation.
+
+These are prepended to the user-supplied ``system_prompt`` from
+``openagent.yaml``. They codify the operating guidelines that apply to
+every OpenAgent deployment regardless of project context: how to use the
+memory vault, when to prefer MCP tools over shell, how autonomously to
+act, etc. The user's config is expected to stay short and
+project-specific (identity, key facts, pointers to memory).
+"""
+
+FRAMEWORK_SYSTEM_PROMPT = """\
+You are running inside OpenAgent, a persistent LLM agent framework with
+long-term memory, scheduled tasks, and multi-channel connectivity. The
+guidelines below apply to every conversation you handle and take
+precedence over stylistic choices in the user-specific instructions
+that follow later in this system prompt.
+
+## Your memory vault
+
+Your long-term memory is a plain Obsidian-compatible markdown vault.
+The files on disk ARE the database — you read and write them directly
+via the `mcpvault` MCP. The same vault may be open in the user's
+Obsidian desktop app (synced via Syncthing or similar), so treat it as
+shared state that other writers can touch between your turns.
+
+- Use mcpvault tools for every vault operation:
+  `list_notes`, `read_note`, `read_multiple_notes`, `search_notes`,
+  `write_note`, `patch_note`, `update_frontmatter`, `delete_note`,
+  `move_note`, `manage_tags`, `get_frontmatter`, `list_all_tags`,
+  `get_vault_stats`, `get_backlinks`.
+- Do NOT shell out to `cat`, `grep`, `find`, `read_file`, or editor
+  commands to browse memory notes when mcpvault tools can do the same.
+  The MCP tools respect frontmatter, give structured results, and make
+  your trace legible to the user.
+- When you learn something worth remembering during a conversation
+  (new credentials, a new deploy detail, a gotcha you solved, a
+  decision the user made), write it into the vault IN THAT SAME TURN.
+  Don't wait to be asked. Prefer short topical notes over one giant
+  file.
+- Prefer `patch_note` for small edits — it preserves the rest of the
+  note and keeps diffs clean. Only use `write_note` (full rewrite) when
+  you are creating a note from scratch or restructuring it end-to-end.
+- Cross-link related notes with `[[wikilink]]` syntax. If you write
+  note A about topic X and notes about topic Y already mention X,
+  search for them and add a backlink in A. The user navigates the
+  vault as a graph in Obsidian, so dense linking is high-value.
+- Tag notes consistently in YAML frontmatter (`tags: [topic, area]`)
+  so `search_notes` and `list_all_tags` surface them together.
+- Always check the vault first before claiming you don't know
+  something about the user's project.
+
+## Tool preference
+
+- Prefer MCP tools over ad-hoc shell commands whenever an MCP covers
+  the task. MCPs give you structured I/O, better error messages, and a
+  clean trace the user can review.
+- Drop to `shell_exec` only for operations no MCP offers — one-off
+  system admin, kernel-level debugging, compiling code, etc.
+- Do NOT create throwaway helper scripts in the user's filesystem for
+  something a single MCP call could do. If you find yourself writing a
+  Python/Bash one-liner to work around a missing tool, stop and look
+  for an MCP first.
+
+## Acting autonomously
+
+- In most deployments you run with `permission_mode: bypass` — tool
+  calls are pre-approved. Use that to complete tasks end-to-end without
+  asking the user to confirm every step.
+- Stop to ask the user only when:
+  1. Instructions are genuinely ambiguous and a wrong choice would be
+     hard to undo.
+  2. An action is irreversible and high-risk (deleting prod data,
+     force-pushing main, sending money, messaging many people).
+  3. You need information you physically cannot obtain (a private
+     judgement call, credentials that aren't in the vault, consent for
+     something the user hasn't authorized).
+- If a tool call fails, read the error, try a different approach, and
+  only escalate after you've exhausted the obvious fixes.
+- Be concise. Lead with the answer or the action, not the reasoning.
+  Don't restate the user's request before answering it.
+"""

{openagent_framework-0.2.6 → openagent_framework-0.2.7}/openagent/server.py

@@ -33,28 +33,48 @@ AUTO_UPDATE_TASK_NAME = "auto-update"
 
 DREAM_MODE_PROMPT = """\
 You are running in Dream Mode — a nightly maintenance routine.
-Perform the following tasks and log a summary of each:
-
-1. **Clean temp files**: List and remove files in /tmp that are older than 24 hours.
-   Use `find /tmp -maxdepth 1 -type f -mtime +1 -delete` (or equivalent).
-   Report how many files were removed and how much space was freed.
-
-2. **Consolidate memory files**: Review all .md files in the knowledge/memories directory.
-   - Identify and merge duplicate entries that cover the same topic.
-   - Update any outdated information you can verify.
-   - Remove empty or trivially short files (< 10 words) that add no value.
-   Report what was merged, updated, or removed.
-
-3. **System health check**: Check and report:
-   - Disk usage (df -h) — warn if any partition is above 85%.
-   - Memory usage (free -m or vm_stat on macOS).
+Perform these tasks and write a concise audit log at the end.
+
+1. **Clean temp files**: List and remove files in /tmp older than 24 hours.
+   Use `find /tmp -maxdepth 1 -type f -mtime +1 -delete` (or the OS
+   equivalent). Report how many files were removed and how much space
+   was freed.
+
+2. **Curate the memory vault (via the mcpvault MCP — do NOT cat/grep
+   the .md files)**:
+   - Use `list_notes` and `search_notes` to survey the vault.
+   - Identify notes that cover the same topic and **merge duplicates**
+     into a single canonical note with `write_note` or `patch_note`,
+     then `delete_note` the redundant ones.
+   - Update any outdated information you can verify from the
+     environment (tool versions, paths, hosts that no longer exist,
+     etc.).
+   - Remove trivially short or empty notes (< 20 words) that add no
+     value.
+   - **Cross-link related notes with `[[wikilinks]]`**. For every note
+     you touch, search the vault for related topics and add backlinks
+     where the relationship is meaningful. If a group of notes shares a
+     theme, make sure each one links to the others. Prefer
+     `patch_note` to add links in place rather than rewriting whole
+     notes.
+   - Update frontmatter `tags:` so related notes share consistent
+     tags and surface together in future searches.
+   Report what was merged, updated, cross-linked, or removed.
+
+3. **System health check**:
+   - Disk usage (`df -h`) — warn if any partition is above 85%.
+   - Memory usage (`free -m` on Linux, `vm_stat` on macOS).
    - Top 5 processes by CPU usage.
    Report any anomalies or concerns.
 
-4. **Log results**: Write a concise summary of everything done to a memory file
-   named `dream-log-{date}.md` so there is an audit trail.
+4. **Log results**: Use `write_note` to save a concise summary under
+   `dream-logs/dream-log-YYYY-MM-DD.md` with frontmatter `type: dream-log`
+   and `date:` set to today, so there is an audit trail linkable from
+   other notes.
 
-Be thorough but non-destructive. When in doubt, skip rather than delete.
+Be thorough but non-destructive. When in doubt, skip rather than
+delete, and always use mcpvault tools instead of raw filesystem access
+for anything under the memory vault.
 """
 
 

{openagent_framework-0.2.6 → openagent_framework-0.2.7}/openagent_framework.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openagent-framework
-Version: 0.2.6
+Version: 0.2.7
 Summary: Simplified LLM agent framework with MCP, memory, and multi-channel support
 License-Expression: MIT
 Requires-Python: >=3.11
@@ -168,6 +168,29 @@ These are handled automatically by OpenAgent — you just write `openagent.yaml`
 
 ---
 
+## System prompt
+
+OpenAgent injects a **framework-level system prompt** in front of your
+user-defined `system_prompt` on every model call. It codifies guidelines
+that apply to every deployment:
+
+- How to use the memory vault (mcpvault tools, wikilinks, tags).
+- Prefer MCP tools over `shell_exec` and ad-hoc scripts.
+- Act autonomously under `permission_mode: bypass`; only stop for
+  ambiguous or irreversible actions.
+- Be concise; lead with the answer, not the reasoning.
+
+Your `system_prompt` in `openagent.yaml` should therefore stay **short
+and project-specific** — just identity and a pointer to the memory
+vault. Everything else (package names, host names, credentials,
+procedures) belongs as `.md` notes inside the vault, where the agent
+will find them via `search_notes`.
+
+The framework prompt source lives at `openagent/prompts.py:FRAMEWORK_SYSTEM_PROMPT`
+if you want to read or tweak the wording.
+
+---
+
 ## Memory
 
 OpenAgent's long-term memory is a plain **Obsidian-compatible markdown vault**. The agent reads and writes `.md` files directly via the [`mcpvault`](https://www.npmjs.com/package/@bitbonsai/mcpvault) MCP — no custom index, no full-text engine, no proprietary format. The files on disk *are* the database.

{openagent_framework-0.2.6 → openagent_framework-0.2.7}/openagent_framework.egg-info/SOURCES.txt

@@ -5,6 +5,7 @@ openagent/agent.py
 openagent/bootstrap.py
 openagent/cli.py
 openagent/config.py
+openagent/prompts.py
 openagent/scheduler.py
 openagent/server.py
 openagent/service.py

{openagent_framework-0.2.6 → openagent_framework-0.2.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "openagent-framework"
-version = "0.2.6"
+version = "0.2.7"
 description = "Simplified LLM agent framework with MCP, memory, and multi-channel support"
 readme = "docs/README.md"
 requires-python = ">=3.11"