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.
