Skip to content

AGENTS.md

Latest commit

 

History

History
102 lines (95 loc) · 10.3 KB

AGENTS.md

File metadata and controls

102 lines (95 loc) · 10.3 KB

Acontext

Acontext is Agent Skills as a Memory Layer for production AI Agents

NAVIGATION GUIDE

  • Python SDK: src/client/acontext-py/
  • TypeScript SDK: src/client/acontext-ts/
  • CLI Tool: src/client/acontext-cli/
  • API: src/server/api/
  • CORE: src/server/core/
  • Dashboard: dashboard/
  • Dashboard (OSS): src/server/ui/
  • OpenClaw Plugin: src/packages/openclaw/ (npm: @acontext/openclaw)
  • Sandbox Cloudflare: src/packages/sandbox-cloudflare/ — a scaffolding/template package (npm: @acontext/create-sandbox-cloudflare). Its prepublishOnly script copies src/server/sandbox/cloudflare/ into template/ with variable substitution, so changes to the Cloudflare Worker source in src/server/sandbox/cloudflare/ are automatically picked up on publish.
  • E2E Tests: src/server/tests/e2e/ — integration tests that run the full stack (API + Core + deps) via docker-compose.test.yml. When modifying server-side behavior, check if e2e coverage should be added or updated.
  • Landing Page: landingpage
  • Documentation: docs/

Plan-driven Development

  • You must make a markdown plan at plans/ before you implement any my request, otherwise I will reject your implementation.
  • The plans/ directory is gitignored — plans are kept locally and do not need to be committed or included in PRs.
  • Remember to update the dev plan after you finish coding.
  • When every task is completed, make sure you check the task checkbox in the corresponding plan.
  • A plan should at least contain features/show case, designs overview, TODOS, new deps, test cases sections.
    • always use the features/show case to present what you're going to build.
    • use checklist in TODOS section, for each checkbox, you must have a clear descripion of what to do and list all the files that will be modified.
    • in new deps section, you must list all the new external dependencies that will be added.
    • in test cases section, use checklist format to list all the test cases that should be covered.

MODULES

  • API is the main module that handles the API requests and responses to Acontext, SDKs are the client-side modules that interact with the API.
  • CLI tool is a command-line tool that helps you deploy Acontext locally and download examples
  • CORE contains the session buffer, task extraction, embedding, agent... anything involving AI/LLM/Agent in it.
  • API and CORE are connected by message queue.
  • API: Go + Gin + GORM/PostgreSQL + Redis + RabbitMQ + S3 + OpenTelemetry + Swagger
  • CORE: Python + FastAPI + SQLAlchemy/PostgreSQL + pgvector + Redis + RabbitMQ + S3 + OpenAI/Anthropic + OpenTelemetry

RULES

Confirm API Schemas before actually implementing them

When you're asked to implement new api endpoints, always lay out the api schema first to let user confirm the input and output are correct.

Update SDKs after modifying API if necessary

When your task is about modify API, always look for the revelant SDKs and see it should be updated.

  • Make sure you update both sync and async sdk in python if updated.

Find Document after modifying SDKs

  • When your task is about implement/update SDKs at src/client, always look for the revelant documents in /docs and see it should be updated.
  • For any doc update in /docs, make sure you read AGENTS-DOC.md.
  • DON't update openapi.json, or swagger.json/yaml. those are artifacts generated by programs, no need to manually edit them. But if they'are changed, that's fine cause they're auto-generated.

Swagger annotations for GORM models

When adding new GORM model fields that use datatypes.JSON, datatypes.JSONMap, or datatypes.JSONType[T], always include the swaggertype struct tag so the Swagger generator (swag) can parse the type. Example: `gorm:"type:jsonb;not null" swaggertype:"object" json:"data"`. Without it, swag will fail with cannot find type definition: datatypes.JSON.

Sync ORMs between API and CORE

Both API and CORE have their ORMs, which should be synced. CORE uses SQLAlchemy, API uses GORM.

Version Bump, Tagging & Release

When releasing a new version, follow these steps in order:

  1. Bump the version number in the package manifest:
    • TypeScript SDK: update "version" in src/client/acontext-ts/package.json
    • Python SDK: update version in src/client/acontext-py/pyproject.toml
    • OpenClaw Plugin: update "version" in src/packages/openclaw/package.json, version in src/packages/openclaw/index.ts (the plugin object), and expect(plugin.version) in src/packages/openclaw/tests/plugin.test.ts
    • Sandbox Cloudflare: update "version" in src/packages/sandbox-cloudflare/package.json
    • Claude Code Plugin: run npm run release -- X.Y.Z in src/packages/claude-code/ — this updates package.json, plugin/.claude-plugin/plugin.json, and .claude-plugin/marketplace.json, then rebuilds the plugin bundles automatically. Full steps: 
      cd src/packages/claude-code
npm run release -- 0.1.1                    # bump 3 version files + rebuild bundles
cd ../../..
git add -A && git commit -m "chore: release claude-code plugin v0.1.1"
git tag package-claude-code/v0.1.1
git push && git push --tags                  # triggers CI: version verify + GitHub Release
      CI (package-release-claude-code.yaml) verifies that all 3 version files match the tag, runs tests, rebuilds bundles and checks that bundle sizes are within 5% of committed artifacts (catches forgotten rebuilds while tolerating cross-platform esbuild differences), then creates a GitHub Release. It does not publish to a registry — the plugin is distributed via the repo itself.
  2. Regenerate the lock file so it stays in sync:
    • TypeScript SDK: run npm install in src/client/acontext-ts/ (updates package-lock.json)
    • Python SDK: run uv lock in src/client/acontext-py/ (updates uv.lock)
    • OpenClaw Plugin: run npm install in src/packages/openclaw/ (updates package-lock.json)
    • Sandbox Cloudflare: no lock file needed (template is synced from src/server/sandbox/cloudflare via prepublishOnly script)
    • Claude Code Plugin: no lock file needed (npm run release already rebuilds bundles)
  3. Commit the version bump + lock file changes.
  4. Tag the commit to trigger the CI/CD release pipeline. Each tag pattern maps to a specific workflow, publish target, and directory:
Component Tag Pattern Publishes To Source Directory Workflow
API api/vX.Y.Z ghcr.io (Docker, multi-arch) src/server/api/go api-release.yaml
Admin API admin/vX.Y.Z ghcr.io (Docker, multi-arch) src/server/api/go admin-release.yaml
Core core/vX.Y.Z ghcr.io (Docker, multi-arch) src/server/core core-release.yaml
UI (OSS) ui/vX.Y.Z ghcr.io (Docker, multi-arch) src/server/ui ui-release.yaml
TypeScript SDK sdk-ts/vX.Y.Z npm (@acontext/acontext) src/client/acontext-ts client-release-ts.yaml
Python SDK sdk-py/vX.Y.Z PyPI (acontext) src/client/acontext-py client-release-py.yaml
CLI cli/vX.Y.Z GitHub Releases (binaries) src/client/acontext-cli cli-release.yaml
OpenClaw Plugin package-openclaw/vX.Y.Z npm (@acontext/openclaw) src/packages/openclaw package-release-openclaw.yaml
Sandbox Cloudflare package-sandbox-cloudflare/vX.Y.Z npm (@acontext/create-sandbox-cloudflare) src/packages/sandbox-cloudflare package-release-sandbox-cloudflare.yaml
Claude Code Plugin package-claude-code/vX.Y.Z Claude Plugin Marketplace src/packages/claude-code package-release-claude-code.yaml
Helm Chart chart/vX.Y.Z ghcr.io (OCI helm chart) charts/acontext publish-chart.yaml

All workflows create a GitHub Release with a path-scoped changelog generated by .github/scripts/generate-changelog.sh. The script finds the previous tag with the same prefix, collects commits scoped to the component's source directory, and groups them by conventional commit type (Features, Bug Fixes, Other). The checkout step in the job that runs generate-changelog.sh must use fetch-depth: 0 so that full git history and tags are available; without it the script cannot find previous tags and falls back to "Initial release." Docker builds produce multi-platform images (linux/amd64, linux/arm64). npm/PyPI workflows skip publishing if the version already exists on the registry. npm packages use OIDC trusted publishers for authentication — do NOT add NODE_AUTH_TOKEN or npm tokens to the publish step.

Pull Requests

  • All PRs must follow the template at .github/PULL_REQUEST_TEMPLATE.md.

Unit Test

  • Always delete the new project you created in the same test

Update Dashboard and Dashboard OSS at the same time

  • Dashboard (dashboard/): The hosted/commercial dashboard with authentication (Supabase), organizations, projects, and a mixin-based AcontextClient. Routes are scoped under /project/[id]/....
  • Dashboard OSS (src/server/ui/): The open-source, self-hosted dashboard.
  • When modifying UI features (types, server actions, page components), always apply the equivalent change to both dashboards.
  • Exception: Encryption features (encryption settings, API key localStorage, key rotation UI) are commercial-only and do NOT need to be added to Dashboard OSS.