The Problem

Building AI agents at scale quickly runs into three concrete roadblocks: (1) storing massive, multimodal LLM message streams in a way that is query‑efficient, (2) keeping long‑running agents stateful without hand‑rolled persistence, and (3) observing task‑level outcomes to close the feedback loop. Acontext is positioned as a shared “context data platform” that supplies a unified storage layer (PostgreSQL, Redis, S3) and higher‑level APIs for sessions, disks, and context editing, so teams do not have to re‑implement these primitives for each product.

What This Does

The repository ships three client SDKs and a server‑side core. The Python SDK lives under src/client/acontext-py/ and exposes acontext.client.Client and resource classes such as async_blocks.AsyncBlocks (see src/client/acontext-py/src/acontext/resources/async_blocks.py). The TypeScript SDK mirrors this surface in src/client/acontext-ts/. A Go‑based CLI (src/client/acontext-cli/main.go) wraps the same operations for scripting and CI. The server core (src/server/core/acontext_core/) implements the data model, async message queue, and LLM tool orchestration; key schema utilities sit in src/server/core/acontext_core/schema/utils.py, which is imported by 62 other modules, making it a stability hotspot.

How It Is Wired

Execution starts at the concrete entry points identified by static analysis:

  • CLI – src/client/acontext-cli/main.go parses sub‑commands (create, docker, upgrade) and ultimately invokes the Go command implementations in src/client/acontext-cli/cmd/*.go. Those commands call into the internal Docker helper (src/client/acontext-cli/internal/docker/manager.go) and the Git helper (src/client/acontext-cli/internal/git/init.go).
  • Python usage – src/client/acontext-py/examples/basic_usage.py runs main (line 280) which creates an acontext.client.Client, then calls high‑traffic functions such as get_session_context (161 callers) and create_new_path_block (74 callers). The call chain quickly reaches the core DB layer (src/server/core/acontext_core/infra/db.py – 14 functions, 31 importers) and the async message queue (src/server/core/acontext_core/infra/async_mq.py – 26 functions, 10 importers).
  • Server API – The Go API entry point is built from src/server/api/go/Dockerfile and started via the Docker compose file src/client/acontext-cli/internal/docker/docker-compose.yaml. The API handler src/server/api/go/internal/modules/handler/session_test.go (representative oversized file) routes HTTP requests to service methods such as create, list, and delete, which in turn call the core functions request and resolve (the latter appears in 18 distinct call sites).

All outbound effects funnel through a small set of functions: get_session_context (database read), delete (DB write + network response), DatabaseClient (DB connection pool), and create_tables (schema migrations). The hub module src/server/core/acontext_core/schema/result.py is imported by 58 files and defines resolve, reject, and unpack, making it the highest‑impact change point. Import cycles exist among the ORM modules (block.py, project.py, space.py), which increase the blast radius of any refactor in that sub‑tree.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/Acontext
cd Acontext

# Build the CLI (Go)
cd src/client/acontext-cli
make          # invokes the Makefile target that runs `go build`

# Install the Python SDK (uv recommended)
cd ../acontext-py
uv pip install .   # reads pyproject.toml

# Spin up the full stack (Docker Compose)
cd ../../client/acontext-cli/internal/docker
docker compose up -d   # uses docker-compose.yaml

# Run a Python example against the local stack
cd ../../../../acontext-py/examples
python basic_usage.py

Configuration values (database URLs, S3 credentials, etc.) are documented in src/server/.env.example. The Helm chart in charts/acontext/ provides a production‑grade deployment option.

Real‑World Use

A SaaS product that runs thousands of concurrent LLM‑driven chat sessions can replace its ad‑hoc PostgreSQL tables with acontext.client.AsyncClient calls to create_new_path_block. Each block write triggers store_message → request → DB insert, and the platform can later query get_session_context to reconstruct a session’s full multimodal history for analytics or fine‑tuning pipelines.

Code Health & Issues

  • HIGH – GitHub Actions use mutable tags (docker/login-action@v3, etc.). Pin to commit SHAs. (.github/workflows/*)
  • MEDIUM – No explicit permissions for GITHUB_TOKEN in cli-test.yaml. Add least‑privilege scopes.
  • MEDIUM – Dockerfile base images (golang:1.25, alpine:3.22) are unpinned; use digests. (src/server/api/go/Dockerfile)
  • MEDIUM – No dependency‑vulnerability scan in CI. Add dependency-review-action or osv-scanner.
  • MEDIUM – Large binary (assets/star_acontext.gif 8.2 MiB) bloats the repo; move to Git LFS or external storage.
  • MEDIUM – Checkout step retains credentials; set persist-credentials: false. (.github/workflows/cli-test.yaml)
  • MEDIUM – Container runs as root; add a non‑root USER. (src/server/api/go/Dockerfile)
  • LOW – Workflow jobs lack timeout-minutes. (.github/workflows/api-release.yaml)
  • LOW – Missing convention files (.editorconfig, .gitattributes, formatter config).

Additional observations: the repo includes a full test suite (78 test files) and CI pipelines for core, API, CLI, and client SDKs, but the import cycles in the ORM layer and deep nesting (indentation depth 10 in several modules) increase maintenance risk.

The Bottom Line

Acontext delivers a multi‑language SDK and a Docker‑ready backend that abstracts context storage, editing, and observability for large‑scale LLM agents. The codebase is functional and well‑tested but suffers from architectural hotspots (a high‑fan‑in schema/result.py, circular ORM imports) and several production‑hardening gaps (unpinned actions, root containers). Teams that need a ready‑made context layer and are comfortable addressing the identified health issues will find it a solid foundation; newcomers should prioritize fixing the hub module and tightening CI/CD security before extending core functionality.