Metadata-Version: 2.4
Name: goldfishmem
Version: 0.1.0
Summary: A production grade memory system for agents
Project-URL: Homepage, https://github.com/MadaraUchiha-314/goldfishmem
Project-URL: Repository, https://github.com/MadaraUchiha-314/goldfishmem
Project-URL: Issues, https://github.com/MadaraUchiha-314/goldfishmem/issues
Author: MadaraUchiha-314
License: MIT License
        
        Copyright (c) 2026 Rohith Ramakrishnan
        
        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.
License-File: LICENSE
Keywords: agents,ai,llm,memory
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# goldfishmem

> A production grade memory system for agents.

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

```python
from goldfishmem import hello_world
```

Consumer-facing documentation lives in [`docs/`](./docs/). This README is the
**developer** guide for working on the project.

## Tech stack

| Concern | Tool |
| --- | --- |
| Language | Python 3.12+ |
| Package manager | [uv](https://docs.astral.sh/uv/) |
| Build backend | [hatchling](https://hatch.pypa.io/) |
| Linter / formatter | [ruff](https://docs.astral.sh/ruff/) |
| Type checker | [pyright](https://microsoft.github.io/pyright/) (strict) |
| Tests | [pytest](https://docs.pytest.org/) + [pytest-cov](https://pytest-cov.readthedocs.io/) |
| Pre-commit | [pre-commit](https://pre-commit.com/) |
| Commit linting | [commitizen](https://commitizen-tools.github.io/commitizen/) (Conventional Commits) |
| Docs | Markdown + [mermaid](https://mermaid.js.org/) diagrams under `docs/` |
| CI/CD | GitHub Actions |
| PyPI publishing | OIDC Trusted Publishing (no API tokens) |

## 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)

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

### 2. Clone and sync dependencies

```bash
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

```bash
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](https://www.conventionalcommits.org/).

You can also run the hooks ad-hoc:

```bash
uv run pre-commit run --all-files
```

### 4. The dev loop

```bash
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:

```bash
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](https://docs.pypi.org/trusted-publishers/)
    (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](https://github.com/MadaraUchiha-314/goldfishmem/issues).
- **Coding-agent contributions**: see [`CLAUDE.md`](./CLAUDE.md) and
  [`AGENT.md`](./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](./LICENSE)
