clawsome 2026.5.4__tar.gz

clawsome-2026.5.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeff Froman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

clawsome-2026.5.4/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: clawsome
+Version: 2026.5.4
+Summary: A lean Python harness for running persistent AI agents
+Author-email: Jeff Froman <79345648+jefffroman@users.noreply.github.com>
+License: MIT
+Project-URL: Homepage, https://github.com/jefffroman/clawsome
+Project-URL: Repository, https://github.com/jefffroman/clawsome
+Project-URL: Issues, https://github.com/jefffroman/clawsome/issues
+Project-URL: Changelog, https://github.com/jefffroman/clawsome/releases
+Project-URL: Documentation, https://github.com/jefffroman/clawsome/blob/main/README.md
+Keywords: ai,agents,claw,matrix,local-inference,persistent-agents,gateway,ollama
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: matrix-nio[e2e]<0.27,>=0.25
+Requires-Dist: httpx>=0.27
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: apscheduler>=3.10
+Requires-Dist: chromadb>=0.5
+Requires-Dist: rank-bm25>=0.2.2
+Requires-Dist: networkx>=3.2
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Dynamic: license-file
+
+<img src="clawsome-logo.png" alt="Clawsome" width="80" align="left">
+
+# Clawsome
+A lean python harness for running persistent AI agents.
+
+> Clawsome is under early, active development. Expect rough edges, breaking changes, and missing features. Feedback and contributions are welcome.
+
+<br clear="left">
+
+
+## Setup
+
+Clawsome talks to a few external services (Ollama, SearXNG, a Matrix
+homeserver) — get those running first, then `pip install -e .` and
+point claw at a populated `claw.yaml`.
+
+→ See [`docs/setup.md`](docs/setup.md) for prerequisites, install notes
+(including the macOS libolm wrinkle), and a first-boot checklist.
+
+## Architecture
+
+A single clawsome process manages **multiple agents**, each with a **workspace** (state on
+disk) and **one or more channels** (inbound surfaces — Matrix is the shipped
+one). Per-turn, the agent loads its transcript, assembles a system prompt
+from injected identity files + retrieved memory, runs an Ollama tool loop,
+and replies. Background tasks (compaction, memory_flush, reindex, cron,
+session rotate) run **off** the user-reply path.
+
+→ See [`docs/architecture.md`](docs/architecture.md) for the full mental
+model, request lifecycle, and workspace file contract.
+
+## Configuration
+
+`claw.yaml` is parsed once at startup; editing requires a restart. The
+shipped `claw.example.yaml` is a runnable template with inline comments.
+
+→ See [`docs/configuration.md`](docs/configuration.md) for the full key-by-key
+reference.
+
+## Operations
+
+Background tuning, daily session rotate, memory retrieval cadence, Matrix
+bot first-deploy (token + cross-signing UIA + ghost-DM avoidance), and
+log-based troubleshooting.
+
+→ See [`docs/operations.md`](docs/operations.md).
+
+## Extending
+
+Three extension points: **skills** (workspace-local; markdown protocol +
+optional `tool.py`), **built-in tools** (in-tree; universal capability),
+**channels** (in-tree; new inbound surface). Skills cover 99% of cases.
+
+→ See [`docs/extending.md`](docs/extending.md).
+
+## Deployment
+
+`pip install` exposes a `claw` console script that takes
+`--config <path/to/claw.yaml>` and runs in the foreground. Wire it into
+launchd / systemd / your process manager of choice as a long-lived service
+running under a dedicated user. This repo intentionally does not ship
+example service files — paths, log destinations, and label/unit names all
+depend on the host layout.
+
+---
+
+## Contributing
+
+Issues and pull requests are welcome on [GitHub](https://github.com/jefffroman/clawsome).

clawsome-2026.5.4/README.md

@@ -0,0 +1,69 @@
+<img src="clawsome-logo.png" alt="Clawsome" width="80" align="left">
+
+# Clawsome
+A lean python harness for running persistent AI agents.
+
+> Clawsome is under early, active development. Expect rough edges, breaking changes, and missing features. Feedback and contributions are welcome.
+
+<br clear="left">
+
+
+## Setup
+
+Clawsome talks to a few external services (Ollama, SearXNG, a Matrix
+homeserver) — get those running first, then `pip install -e .` and
+point claw at a populated `claw.yaml`.
+
+→ See [`docs/setup.md`](docs/setup.md) for prerequisites, install notes
+(including the macOS libolm wrinkle), and a first-boot checklist.
+
+## Architecture
+
+A single clawsome process manages **multiple agents**, each with a **workspace** (state on
+disk) and **one or more channels** (inbound surfaces — Matrix is the shipped
+one). Per-turn, the agent loads its transcript, assembles a system prompt
+from injected identity files + retrieved memory, runs an Ollama tool loop,
+and replies. Background tasks (compaction, memory_flush, reindex, cron,
+session rotate) run **off** the user-reply path.
+
+→ See [`docs/architecture.md`](docs/architecture.md) for the full mental
+model, request lifecycle, and workspace file contract.
+
+## Configuration
+
+`claw.yaml` is parsed once at startup; editing requires a restart. The
+shipped `claw.example.yaml` is a runnable template with inline comments.
+
+→ See [`docs/configuration.md`](docs/configuration.md) for the full key-by-key
+reference.
+
+## Operations
+
+Background tuning, daily session rotate, memory retrieval cadence, Matrix
+bot first-deploy (token + cross-signing UIA + ghost-DM avoidance), and
+log-based troubleshooting.
+
+→ See [`docs/operations.md`](docs/operations.md).
+
+## Extending
+
+Three extension points: **skills** (workspace-local; markdown protocol +
+optional `tool.py`), **built-in tools** (in-tree; universal capability),
+**channels** (in-tree; new inbound surface). Skills cover 99% of cases.
+
+→ See [`docs/extending.md`](docs/extending.md).
+
+## Deployment
+
+`pip install` exposes a `claw` console script that takes
+`--config <path/to/claw.yaml>` and runs in the foreground. Wire it into
+launchd / systemd / your process manager of choice as a long-lived service
+running under a dedicated user. This repo intentionally does not ship
+example service files — paths, log destinations, and label/unit names all
+depend on the host layout.
+
+---
+
+## Contributing
+
+Issues and pull requests are welcome on [GitHub](https://github.com/jefffroman/clawsome).

clawsome-2026.5.4/claw/__init__.py

@@ -0,0 +1 @@
+__version__ = "2026.5.4"