strands-github-storage (Python)
A GitHub-repository Storage backend for Strands Agents.
Persists each key as a file in a GitHub repository, at the key's path on a branch. Because the store
is a git repo, its contents are browsable in the GitHub UI, diffable per change, and versioned in
history. Implements the SDK's Storage interface, so it works anywhere a Storage is accepted —
session snapshots and context offloading.
Install
pip install strands-github-storage
strands-agents and PyGithub are installed as dependencies.
Usage
import asyncio
from strands_github_storage import GithubStorage
storage = GithubStorage(
owner="myorg",
repo="agent-memory",
branch="main", # optional, defaults to "main"
token="ghp_...", # required for writes and private repos
)
async def main() -> None:
await storage.write("facts/note.md", b"remember this")
data = await storage.read("facts/note.md") # bytes | None
keys = await storage.list("facts/") # ["facts/note.md"]
await storage.delete("facts/note.md")
asyncio.run(main())
With a session manager
from strands import Agent
from strands.session import SnapshotSessionManager
from strands_github_storage import GithubStorage
storage = GithubStorage(owner="myorg", repo="agent-sessions", token="ghp_...")
agent = Agent(session_manager=SnapshotSessionManager("agent-sessions", storage=storage))
Configuration
| Parameter | Required | Description |
|---|---|---|
owner |
yes | Repository owner (user or organization login). |
repo |
yes | Repository name. |
branch |
no | Branch to read from and commit to. Defaults to main. |
token |
for writes | GitHub token. Needed for any write and for reading private repos. |
github |
no | A pre-configured PyGithub Github client, as an alternative to token. |
Behavior and limits
- One commit per operation. Each
writeanddeleteis its own commit (update <key>/delete <key>). A burst of writes produces a burst of commits. - Single writer per branch. Commits advance the branch ref without a compare-and-swap retry, so a
concurrent writer that moves the branch head surfaces GitHub's non-fast-forward rejection as a
StorageErrorrather than being retried. readis limited to files under the GitHub contents API's inline-response ceiling (~1 MB). Markdown memory is far below this.listfails loud on truncation. GitHub's git-tree API caps very large trees and does not paginate; rather than return a silent partial listing,listraises aStorageError.
Development
pip install -e ".[dev]"
pytest
ruff check src tests
mypy src
License
Apache-2.0
Metadata
Release files for strands-github-storage 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| strands_github_storage-0.1.1.tar.gz | 9.7 kB | Without provenance | Details for strands_github_storage-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| strands_github_storage-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for strands_github_storage-0.1.1-py3-none-any.whl |
Total release size: 19.6 kB
Release files / strands_github_storage-0.1.1.tar.gz
| Download URL | strands_github_storage-0.1.1.tar.gz |
|---|---|
| Size | 9.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
cd013b039e5d913fd5134322d4ee60151ed0f73ff0f0ea6311f7007ab84a13cd
|
|
BLAKE2b-256 checksum How to use checksums |
f3eec15f1ebb56d1f5ec0189596e0636cd9d9481a4886a6547112cb737a01ea9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.5
|
Release files / strands_github_storage-0.1.1-py3-none-any.whl
| Download URL | strands_github_storage-0.1.1-py3-none-any.whl |
|---|---|
| Size | 9.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1fae6518a1e9bd06d9cc3eb7fff82c764b75c999a933a18ccebd868c6de2327b
|
|
BLAKE2b-256 checksum How to use checksums |
8b4b30b273f1cdce4e128eea90c753fb20f83eb89b8354fca4c40fc9a0d96572
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.5
|
Security for strands-github-storage 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.