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:

uv tool install agent-activity
# Or: pipx install agent-activity

For development from a source checkout:

uv tool install .

Run setup from the project that should use memory:

agent-activity install opencode --profile work

Or make it available across your projects:

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:

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.

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:

agent-activity --profile work serve

Use these commands to get portable configuration and policy text:

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:

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

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.

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:

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.

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

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.

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.

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 for the full terms and limitation of liability.