goldfishmem

A production grade memory system for agents.

goldfishmem is published on PyPI under the same name. The Python import name matches the distribution:

from goldfishmem import hello_world

Consumer-facing documentation lives in docs/. This README is the developer guide for working on the project.

Tech stack

Repository layout

goldfishmem/          # source package (all code lives here, import as `goldfishmem`)
tests/
  unit/               # fast unit tests
  integration/        # integration tests (also gated on the `integration` marker)
docs/                 # consumer-facing documentation
.claude/              # Claude Code permissions/skills/plugins
.mcp.json             # MCP server registrations (chrome-devtools, Lucid)
.github/workflows/    # ci.yml, release.yml
CLAUDE.md             # guidance for Claude
AGENT.md / AGENTS.md  # guidance for Cursor and other agents
CONTRIBUTING.md       # contributor guide

Local development

1. Install uv (one-time)

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Clone and sync dependencies

git clone https://github.com/MadaraUchiha-314/goldfishmem.git
cd goldfishmem
uv sync

uv sync creates .venv/ in the project root and installs runtime + dev dependencies from pyproject.toml.

3. Install the pre-commit hooks

uv run pre-commit install --hook-type pre-commit --hook-type commit-msg

This installs two hooks:

• pre-commit — runs ruff check, ruff format, pyright, and the unit test suite on every commit.
• commit-msg — runs commitizen check to enforce Conventional Commits.

You can also run the hooks ad-hoc:

uv run pre-commit run --all-files

4. The dev loop

uv run ruff check .              # lint
uv run ruff format .             # format
uv run pyright                   # type-check (strict)
uv run pytest tests/unit         # unit tests
uv run pytest tests/integration  # integration tests

5. Writing a commit

Either format the message yourself (feat: ..., fix: ..., etc.) or use the interactive helper:

uv run cz commit

CI/CD

• .github/workflows/ci.yml — runs on every PR and on push to main:
  • ruff check and ruff format --check
  • pyright (strict)
  • Unit tests against Python 3.12 and 3.13
  • Integration tests
  • Commit-message linting on PRs
• .github/workflows/release.yml — runs on push to main after CI passes:
  • cz bump --yes --changelog computes the next semver from the conventional commits since the last tag, updates pyproject.toml and goldfishmem/__init__.py, and updates CHANGELOG.md.
  • Pushes the version-bump commit and the new tag back to main.
  • Builds the sdist + wheel with uv build.
  • Publishes to PyPI via OIDC Trusted Publishing (no PYPI_API_TOKEN secret needed — configure the PyPI project under Settings → Publishing to trust this GitHub repo + release.yml).
  • Creates a GitHub Release with the changelog and dist artifacts attached.

One-time PyPI Trusted Publisher setup

Before the first release succeeds, configure PyPI:

1. Reserve the project name goldfishmem on https://pypi.org by uploading a first version manually, OR pre-create the project via "pending publisher" under your PyPI account → Publishing → Add a new pending publisher.
2. Add a trusted publisher with:
   • Owner: MadaraUchiha-314
   • Repository: goldfishmem
   • Workflow filename: release.yml
   • Environment name: pypi
3. In this repo's settings, create a GitHub Environment named pypi.

Project management

• Roadmap, features, bugs: tracked on GitHub Projects.
• Community feedback: open a GitHub Issue.
• Coding-agent contributions: see CLAUDE.md and AGENT.md. Agents must post a plan with a [Plan by <agent>] prefix on the relevant issue and wait for human approval before implementing.

License

MIT