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

Behavior and limits

• One commit per operation. Each write and delete is 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 StorageError rather than being retried.
• read is limited to files under the GitHub contents API's inline-response ceiling (~1 MB). Markdown memory is far below this.
• list fails loud on truncation. GitHub's git-tree API caps very large trees and does not paginate; rather than return a silent partial listing, list raises a StorageError.

Development

pip install -e ".[dev]"
pytest
ruff check src tests
mypy src

License

Apache-2.0