agent-activity 0.1.0__tar.gz

agent_activity-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: Package checks
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ['3.11', '3.15']
+    runs-on: ${{ matrix.os }}
+    defaults:
+      run:
+        shell: bash
+    env:
+      PYTHONUTF8: '1'
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: python -m pip install build 'mcp>=1.12,<2'
+      - run: python -m build
+      - run: python -m pip install dist/*.whl
+      - run: python -m unittest discover -s tests -v
+      - run: agent-activity --version

agent_activity-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,85 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test Python ${{ matrix.python }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ['3.11', '3.15']
+    env:
+      PYTHONUTF8: '1'
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install locked development tools
+        run: python -m pip install uv==0.12.17
+      - name: Run tests from the locked environment
+        run: |
+          uv sync --locked --group dev
+          uv run --locked --group dev python -m unittest discover -s tests -v
+
+  build:
+    name: Build and verify distributions
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: '3.11'
+      - name: Install locked development tools
+        run: python -m pip install uv==0.12.17
+      - name: Check release tag matches package version
+        shell: bash
+        run: |
+          uv sync --locked --group dev
+          package_version="$(uv run --locked --group dev python -c 'import agent_activity; print(agent_activity.__version__)')"
+          project_version="$(uv run --locked --group dev python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')"
+          test "$package_version" = "$project_version"
+          test "$GITHUB_REF_NAME" = "v$project_version"
+      - name: Audit locked dependencies
+        run: uv run --locked --group dev pip-audit --skip-editable
+      - name: Build wheel and source distribution
+        run: uv run --locked --group dev python -m build --sdist --wheel
+      - name: Validate distribution metadata
+        run: uv tool run --from twine twine check dist/*
+      - name: Smoke-test the installed wheel and MCP tools
+        run: uv run --locked --group dev python scripts/smoke_distribution.py dist/*.whl
+      - uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5
+        with:
+          name: python-package-distributions
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    name: Publish distributions to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/agent-activity/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6
+        with:
+          name: python-package-distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # release/v1

agent_activity-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+*.egg-info/
+*.sqlite*
+*.db*
+*.agent-activity-*.bak
+.env
+.env.*

agent_activity-0.1.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+Notable changes to agent-activity are recorded here.
+
+## [Unreleased]
+
+### Added
+
+- Added current-release feature and potential future-work checklists.
+- Added Makefile shortcuts for syncing development dependencies, testing, building,
+  running checks, and starting the MCP server.
+- Added tag-triggered PyPI publishing with Trusted Publishing, cross-platform release
+  tests, dependency auditing, distribution validation, and an installed-wheel MCP
+  smoke test.
+
+## [0.1.0]
+
+### Added
+
+- Local SQLite task memory with profile isolation, retry deduplication, and concurrent writers.
+- JSON CLI and stdio MCP tools for recording, recalling, and checking activity.
+- Setup integrations for OpenCode, Claude Code, Codex, Cursor, VS Code Copilot, and Gemini CLI.
+- Portable configuration, database migrations, and cross-platform test coverage.

agent_activity-0.1.0/FEATURES.md

@@ -0,0 +1,13 @@
+# Features
+
+Capabilities in the current release:
+
+- [x] Store concise agent task history in a local SQLite database.
+- [x] Provide `record`, `recent`, and `health` stdio MCP tools.
+- [x] Provide a JSON CLI for logging and querying activity.
+- [x] Scope records by profile and project, with idempotent retry keys.
+- [x] Support concurrent writers and preserve existing databases through schema migrations.
+- [x] Install MCP configuration and recording/recall instructions for OpenCode, Claude Code,
+  Codex, Cursor, VS Code Copilot, and Gemini CLI.
+- [x] Keep runtime dependencies at zero and support Python 3.11+.
+- [x] Test storage, protocol behavior, integrations, and MCP SDK handshake flows.

agent_activity-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Keith Connolly
+
+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.

agent_activity-0.1.0/Makefile

@@ -0,0 +1,40 @@
+UV ?= uv
+PROFILE ?= default
+
+.DEFAULT_GOAL := help
+.PHONY: help sync test audit build package-check check release-check serve
+
+help:
+	@printf '%s\n' \
+	  'agent-activity development tasks' \
+	  '  make sync                 Sync development dependencies' \
+	  '  make test                 Run the unittest suite' \
+	  '  make audit                Audit locked development dependencies' \
+	  '  make build                Build wheel and source distribution' \
+	  '  make package-check        Validate and smoke-test the wheel' \
+	  '  make check                Run tests and package checks' \
+	  '  make release-check        Run the complete release verification' \
+	  '  make serve PROFILE=work   Start the stdio MCP server'
+
+sync:
+	$(UV) sync --locked --group dev
+
+test:
+	$(UV) run --locked --group dev python -m unittest discover -s tests -v
+
+audit:
+	$(UV) run --locked --group dev pip-audit --skip-editable
+
+build:
+	$(UV) run --locked --group dev python -m build --sdist --wheel
+
+package-check: build
+	$(UV) run --locked --group dev twine check dist/*
+	$(UV) run --locked --group dev python scripts/smoke_distribution.py dist/*.whl
+
+check: test audit package-check
+
+release-check: check
+
+serve:
+	$(UV) run --locked --group dev agent-activity --profile "$(PROFILE)" serve

agent_activity-0.1.0/PKG-INFO

@@ -0,0 +1,262 @@
+Metadata-Version: 2.5
+Name: agent-activity
+Version: 0.1.0
+Summary: Small, local SQLite task memory for coding agents, with a CLI and stdio MCP server.
+Author: Keith Connolly
+License-Expression: MIT
+License-File: LICENSE
+Keywords: activity,agent,mcp,memory,sqlite
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# agent-activity
+
+Small, local SQLite task memory for coding agents. Keep a useful history of what
+was done, what was verified, and what actually happened, across sessions and
+harnesses.
+
+- One SQLite file and **zero runtime dependencies**. Python 3.11+.
+- CLI plus three stdio MCP tools: `record`, `recent`, and `health`.
+- Setup for OpenCode V2, Claude Code, Codex, Cursor, VS Code Copilot, and Gemini CLI.
+- Named profiles, concurrent writers, and idempotent record retries.
+- Portable configuration and a user-configurable SQLite database location.
+
+## Install
+
+Install the command-line tool from PyPI:
+
+```sh
+uv tool install agent-activity
+# Or: pipx install agent-activity
+```
+
+For development from a source checkout:
+
+```sh
+uv tool install .
+```
+
+Run setup from the project that should use memory:
+
+```sh
+agent-activity install opencode --profile work
+```
+
+Or make it available across your projects:
+
+```sh
+agent-activity install claude-code --scope user --profile work
+agent-activity install codex --scope user --profile work
+```
+
+Setup writes the MCP configuration **and** the instructions to record and recall
+tasks. Restart the harness afterward. Enable the server if your harness prompts,
+then ask it to call the `activity` server's `health` tool. This checks the connection
+without adding a record.
+
+Use `--dry-run` to list affected files without creating files or opening SQLite:
+
+```sh
+agent-activity install opencode --scope user --profile work --dry-run
+```
+
+The installer preserves unrelated config and comments, replaces only the named
+JSON server entry, and updates a marked instruction block. Existing changed files
+get unique `.agent-activity-<id>.bak` backups. Repeating the
+same installation makes no further changes. Codex TOML entries are managed inside
+marked blocks; an existing unmarked server of the same name must be edited
+manually or installed under a different `--name`.
+
+## Harness support
+
+Project scope is the default. `--root /path/to/project` selects a different project.
+
+| Harness argument | Project MCP config | Project instructions | User scope |
+| --- | --- | --- | --- |
+| `opencode` | `opencode.json(c)` or existing `.opencode/opencode.json(c)` | `AGENTS.md` | Yes, honors `OPENCODE_CONFIG_DIR` and `XDG_CONFIG_HOME` |
+| `claude-code` | `.mcp.json` | `CLAUDE.md` | Yes |
+| `codex` | `.codex/config.toml` | `AGENTS.md`, or existing `AGENTS.override.md` | Yes, honors `CODEX_HOME` |
+| `cursor` | `.cursor/mcp.json` | `.cursor/rules/agent-activity.mdc`, always applied | Manual user rules, see below |
+| `vscode` | `.mcp.json` | `.github/copilot-instructions.md` | Yes, for the current Copilot harness |
+| `gemini` | `.gemini/settings.json` | `GEMINI.md` | Yes |
+
+```sh
+agent-activity install cursor --profile personal
+agent-activity install vscode --profile work
+agent-activity install gemini --scope user --profile personal
+```
+
+VS Code setup targets its current Copilot harness and the portable `mcpServers`
+format. For older VS Code Local sessions using `.vscode/mcp.json`, copy the server
+entry into the top-level `servers` object instead. VS Code's Claude and Codex
+harnesses use their respective adapters.
+
+Cursor user-wide setup needs its user rule UI: merge `config cursor` into
+`~/.cursor/mcp.json`, then paste `instructions` into **Customize → Rules → User Rules**.
+The automatic Cursor installer uses project rules so both halves are installed.
+
+For any other stdio MCP client, launch:
+
+```sh
+agent-activity --profile work serve
+```
+
+Use these commands to get portable configuration and policy text:
+
+```sh
+agent-activity config claude-code --profile work
+agent-activity config codex --profile work
+agent-activity instructions --profile work
+```
+
+`config` prints a fragment, not a replacement for the whole harness configuration.
+`install` and `config` use the portable `agent-activity` executable name. Install
+it on each machine and make it available on the harness's PATH, including for GUI
+applications. Default configuration contains no home-directory, interpreter, or
+database paths from the machine running setup. Database paths are included only
+when explicitly supplied with `--db`; quote a path starting with `~` to preserve
+it for expansion on the machine running the server.
+
+## Profiles and storage
+
+The default file is `~/.agent-activity/activity.sqlite`. Path precedence:
+
+1. `--db /path/to/file.sqlite`
+2. `AGENT_ACTIVITY_DB`
+3. The default path above
+
+Each server resolves its database path when it starts. A relative `--db` path is
+relative to the server's working directory; a path starting with `~` resolves
+against that machine's user home.
+
+The profile defaults to `AGENT_ACTIVITY_PROFILE`, then `default`. Choose `work`,
+`personal`, or any 1-64 character name using letters, digits, `.`, `_`, and `-`.
+Profiles are fixed when the server starts, never supplied through MCP tool input.
+
+Point different harnesses at the same database and profile to share history.
+Use separate profiles to keep work and personal recall separate:
+
+```sh
+agent-activity --profile work recent
+agent-activity --profile personal recent
+```
+
+Profile scoping is enforced by the tools, not an OS security boundary. A user with
+filesystem access can read the complete file. POSIX databases are mode `600` and
+the default memory directory is `700`; Windows uses the account's directory ACLs.
+
+## Tools and CLI
+
+| Tool | Purpose |
+| --- | --- |
+| `record` | Save one task's sanitized summary and outcome, with a stable retry key |
+| `recent` | Read the latest records for the profile, optionally filtered by project |
+| `health` | SQLite integrity check and profile-scoped record count |
+
+`record` requires `project` (a canonical repository name or `null`), `action_type`,
+`summary`, `outcome`, and `event_key`. Optional `metadata` is a JSON object.
+The profile cannot be changed by tool arguments.
+
+```sh
+agent-activity --profile work log example-app investigation \
+  "Traced the retry path" "Verified the failure handling" --event-key unique-task-key
+agent-activity --profile work project example-app 10
+agent-activity --profile work today
+agent-activity --profile work general
+agent-activity --profile work projects
+agent-activity --profile work types
+agent-activity --profile work health
+```
+
+CLI output is JSON. `log` accepts `-` for general work and an optional final JSON
+metadata object. Without `--event-key`, each CLI invocation generates a UUID.
+CLI and MCP retry scopes are separate. Identical retries in the same profile/scope
+return the original ID; reusing a key with different content fails.
+
+OpenCode's session extension provides a hashed session retry scope.
+Other clients need no extension: choose a unique task key, such as a UUID, and
+reuse it only for retries. Raw session IDs are not stored.
+
+Action types: `setup`, `code_change`, `investigation`, `review`, `config_change`,
+`test`, `deploy`, `blocked`, and `note`.
+
+## How memory gets written
+
+The installed policy asks the agent to recall relevant activity when resuming
+work and record one meaningful completed or blocked task before the final reply.
+The MCP server also supplies the same policy during initialization.
+
+Recording depends on the model following these instructions. Retry deduplication
+does not guarantee that every task will be recorded. The package doesn't collect
+transcripts, backfill old sessions, or run background summarization.
+
+Store concise outcomes and verification details. Callers must omit secrets, raw
+prompts/tool output, customer data, source snippets, and signed URLs. The package
+does not automatically redact arbitrary sensitive content.
+
+## Existing databases
+
+Select an existing compatible database explicitly:
+
+```sh
+agent-activity --profile work --db /path/to/existing/activity.sqlite health
+```
+
+Schema migration preserves existing rows and retry keys. Older unscoped rows
+are retained under `legacy`, never assigned to a guessed profile. The auxiliary
+`observations`, `artifacts`, `tags`, and `action_tags` tables are retained.
+
+Use `--profile` or `AGENT_ACTIVITY_PROFILE` to select a namespace. Automatic setup
+writes an explicit profile into each server command. Keep one activity server
+enabled per harness/profile.
+
+## Updating and removing
+
+Update the tool from a new wheel or checkout. Keep the `agent-activity` executable
+on the harness's PATH and keep the database outside the package folder.
+
+To remove an integration, delete the named MCP entry (or its marked TOML block)
+and the `agent-activity` marked instruction block. Restore a printed backup if
+you want the exact pre-install file. For Cursor, remove the dedicated `.mdc` file
+if it contains only this package's rule.
+
+```sh
+uv tool uninstall agent-activity
+# Or: pipx uninstall agent-activity
+```
+
+The database is retained. Use SQLite's backup API for live database backups;
+copying only the main file can miss uncheckpointed journal/WAL data.
+
+## Development and distribution
+
+```sh
+make sync
+make release-check
+```
+
+Release checks run the test suite, audit locked development dependencies, build
+both distributions, validate their metadata, and install the wheel in an isolated
+environment for an MCP smoke test. The CI workflow tests on Linux, macOS, and
+Windows; see [verification and release notes](docs/releasing.md).
+
+There are no service accounts, API keys, hosted services, or model subscriptions
+required by this package itself.
+
+## License and attribution
+
+Copyright (c) 2026 Keith Connolly. Released under the [MIT License](LICENSE).
+
+You may use, modify, share, sublicense, and sell this software, including in
+commercial and closed-source projects. Keep the copyright and license notice in
+copies or substantial portions of the software, as required by the MIT License.
+
+Additional credit to Keith Connolly in your documentation or acknowledgments is
+appreciated, but is not an additional license requirement.
+
+The software is provided "as is", without warranty. See [LICENSE](LICENSE) for
+the full terms and limitation of liability.