Skip to content

memodb-io/Acontext

Show Acontext header banner

Engineer Contexts, Learn Skills

Twitter Follow Acontext Discord


Acontext is a context data platform for building cloud-native AI Agents. It can:

  • Store contexts & artifacts.
  • Do context engineering for you.
  • Observe agent tasks and user feedback.
  • Enable agent self-learning by distilling skills from agent's completed tasks.
  • View everything in one Dashboard.
Acontext Learning

Context Data Platform that Store, Observe and Learn

Acontext can help you:

  • Build a more scalable agent product with better context engineering
  • Build a truly observable Agent product.
  • Automatically improve your agent success rate

💡 Core Features

  • Session - Multi-modal Message Storage
    • Task Agent - Background TODO agent that collects task's status, progress and preferences
    • Context Editing - Context Engineering in one call
  • Disk - Filesystem for artifacts
  • Space - Notion for agents
  • Dashboard - View messages, artifacts, skills, success rates and everything

How They Work Together

┌──────┐ ┌────────────┐ ┌──────────────┐ ┌───────────────┐ │ User │◄──►│ Your Agent │◄──►│ Session │ │ Artifact Disk │ └──────┘ └─────▲──────┘ └──────┬───────┘ └───────────────┘ │ │ # if enable │ ┌────────▼────────┐ │ │ Observed Tasks │ │ └────────┬────────┘ │ │ # if enable │ ┌────────▼────────┐ │ │ Learn Skills │ │ └────────┬────────┘ └──────────────────┘ Search skills

🏗️ Architecture

Click to open the architecture diagram, if you're interested.
graph TB subgraph "Client Layer" PY["pip install acontext"] TS["npm i @acontext/acontext"] end subgraph "Acontext Backend" subgraph " " API["API<br/>localhost:8029"] CORE["Core"] API -->|FastAPI & MQ| CORE end subgraph " " Infrastructure["Infrastructures"] PG["PostgreSQL"] S3["S3"] REDIS["Redis"] MQ["RabbitMQ"] end end subgraph "Dashboard" UI["Web Dashboard<br/>localhost:3000"] end PY -->|RESTFUL API| API TS -->|RESTFUL API| API UI -->|RESTFUL API| API API --> Infrastructure CORE --> Infrastructure Infrastructure --> PG Infrastructure --> S3 Infrastructure --> REDIS Infrastructure --> MQ style PY fill:#3776ab,stroke:#fff,stroke-width:2px,color:#fff style TS fill:#3178c6,stroke:#fff,stroke-width:2px,color:#fff style API fill:#00add8,stroke:#fff,stroke-width:2px,color:#fff style CORE fill:#ffd43b,stroke:#333,stroke-width:2px,color:#333 style UI fill:#000,stroke:#fff,stroke-width:2px,color:#fff style PG fill:#336791,stroke:#fff,stroke-width:2px,color:#fff style S3 fill:#ff9900,stroke:#fff,stroke-width:2px,color:#fff style REDIS fill:#dc382d,stroke:#fff,stroke-width:2px,color:#fff style MQ fill:#ff6600,stroke:#fff,stroke-width:2px,color:#fff 
Loading

Data Structures

📖 Task Structure
{ "task_description": "Star https://github.com/memodb-io/Acontext", "progresses": [ "I have navigated to Acontext repo", "Tried to Star but a pop-up required me to login", ... ], "user_preferences": [ "user wants to use outlook email to login" ] }
📖 Skill Structure
{ "use_when": "star a repo on github.com", "preferences": "use user's outlook account", "tool_sops": [ {"tool_name": "goto", "action": "goto github.com"}, {"tool_name": "click", "action": "find login button if any. login first"}, ... ] }
📖 Space Structure
/ └── github/ (folder) └── GTM (page) ├── find_trending_repos (sop) └── find_contributor_emails (sop) └── basic_ops (page) ├── create_repo (sop) └── delete_repo (sop) ...

🚀 Start the Backend Locally

We have an acontext-cli to help you do quick proof-of-concept. Download it first in your terminal:

curl -fsSL https://install.acontext.io | sh

You should have docker installed and an OpenAI API Key to start an Acontext backend on your computer:

mkdir acontext_server && cd acontext_server acontext docker up

📖 local setup Acontext requires at least an OpenAI API key. We recommend gpt-5.1 or gpt-4.1 as the LLM model

acontext docker up will create/use .env and config.yaml for Acontext, and create a db folder to persist data.

Once it's done, you can access the following endpoints:

Dashboard

Dashboard of Agent Success Rate and Other Metrics

🧐 Use Acontext to build Agent

Download end-to-end scripts with acontext:

Python

acontext create my-proj --template-path "python/openai-basic"

More examples on Python:

  • python/openai-agent-basic: self-learning agent in openai agent sdk.
  • python/agno-basic: self-learning agent in agno frameworkd.
  • python/openai-agent-artifacts: agent that can edit and download artifacts.

Typescript

acontext create my-proj --template-path "typescript/openai-basic"

More examples on Typescript:

  • typescript/vercel-ai-basic: self-learning agent in @vercel/ai-sdk

Check our example repo for more templates: Acontext-Examples.

Step-by-step Quickstart

Click to Open

We're maintaining Python pypi and Typescript npm SDKs. The snippets below are using Python.

Install SDKs

pip install acontext # for Python npm i @acontext/acontext # for Typescript 

Initialize Client

from acontext import AcontextClient client = AcontextClient( base_url="http://localhost:8029/api/v1", api_key="sk-ac-your-root-api-bearer-token" ) client.ping() # yes, the default api_key is sk-ac-your-root-api-bearer-token

📖 async client doc

Store

Acontext can manage agent sessions and artifacts.

Save Messages 📖

Acontext offers persistent storage for message data. When you call session.store_message, Acontext will persist the message and start to monitor this session:

Code Snippet
session = client.sessions.create() messages = [ {"role": "user", "content": "I need to write a landing page of iPhone 15 pro max"}, { "role": "assistant", "content": "Sure, my plan is below:\n1. Search for the latest news about iPhone 15 pro max\n2. Init Next.js project for the landing page\n3. Deploy the landing page to the website", } ] # Save messages for msg in messages: client.sessions.store_message(session_id=session.id, blob=msg, format="openai")

📖 We also support multi-modal message storage and anthropic SDK.

Load Messages 📖

Obtain your session messages using sessions.get_messages

Code Snippet
r = client.sessions.get_messages(session.id) new_msg = r.items new_msg.append({"role": "user", "content": "How are you doing?"}) r = openai_client.chat.completions.create(model="gpt-4.1", messages=new_msg) print(r.choices[0].message.content) client.sessions.store_message(session_id=session.id, blob=r.choices[0].message)
Session

You can view sessions in your local Dashboard

Artifacts 📖

Create a disk for your agent to store and read artifacts using file paths:

Code Snippet
from acontext import FileUpload disk = client.disks.create() file = FileUpload( filename="todo.md", content=b"# Sprint Plan\n\n## Goals\n- Complete user authentication\n- Fix critical bugs" ) artifact = client.disks.artifacts.upsert( disk.id, file=file, file_path="/todo/" ) print(client.disks.artifacts.list( disk.id, path="/todo/" )) result = client.disks.artifacts.get( disk.id, file_path="/todo/", filename="todo.md", with_public_url=True, with_content=True ) print(f"✓ File content: {result.content.raw}") print(f"✓ Download URL: {result.public_url}") 
Artifacts

You can view artifacts in your local Dashboard

Observe 📖

For every session, Acontext will automatically launch a background agent to track the task progress and user feedback. It's like a background TODO agent. Acontext will use it to observe your daily agent success rate.

You can use the SDK to retrieve the current state of the agent session, for Context Engineering like Reduction and Compression.

Full Script
from acontext import AcontextClient # Initialize client client = AcontextClient( base_url="http://localhost:8029/api/v1", api_key="sk-ac-your-root-api-bearer-token" ) # Create a project and session session = client.sessions.create() # Conversation messages messages = [ {"role": "user", "content": "I need to write a landing page of iPhone 15 pro max"}, { "role": "assistant", "content": "Sure, my plan is below:\n1. Search for the latest news about iPhone 15 pro max\n2. Init Next.js project for the landing page\n3. Deploy the landing page to the website", }, { "role": "user", "content": "That sounds good. Let's first collect the message and report to me before any landing page coding.", }, { "role": "assistant", "content": "Sure, I will first collect the message then report to you before any landing page coding.", "tool_calls": [ { "id": "call_001", "type": "function", "function": { "name": "search_news", "arguments": "{\"query\": \"iPhone news\"}" } } ] }, ] # Store messages in a loop for msg in messages: client.sessions.store_message(session_id=session.id, blob=msg, format="openai") # Wait for task extraction to complete client.sessions.flush(session.id) # Display extracted tasks tasks_response = client.sessions.get_tasks(session.id) print(tasks_response) for task in tasks_response.items: print(f"\nTask #{task.order}:") print(f" ID: {task.id}") print(f" Title: {task.data.task_description}") print(f" Status: {task.status}") # Show progress updates if available if task.data.progresses: print(f" Progress updates: {len(task.data.progresses)}") for progress in task.data.progresses: print(f" - {progress}") # Show user preferences if available if task.data.user_preferences: print(" User preferences:") for pref in task.data.user_preferences: print(f" - {pref}")

flush is a blocking call, it will wait for the task extraction to complete. You don't need to call it in production, Acontext has a buffer mechanism to ensure the task extraction is completed right on time.

Example Task Return:

Task #1: Title: Search for the latest news about iPhone 15 Pro Max and report findings to the user before any landing page coding. Status: success Progress updates: 2 - I confirmed that the first step will be reporting before moving on to landing page development. - I have already collected all the iPhone 15 pro max info and reported to the user, waiting for approval for next step. User preferences: - user expects a report on latest news about iPhone 15 pro max before any coding work on the landing page. Task #2: Title: Initialize a Next.js project for the iPhone 15 Pro Max landing page. Status: pending Task #3: Title: Deploy the completed landing page to the website. Status: pending

You can view the session tasks' statuses in the Dashboard:

Acontext Learning

A Task Demo

Self-learning

Acontext can gather a bunch of sessions and learn skills (SOPs) on how to call tools for certain tasks.

Learn Skills to a Space 📖

A Space Demo

How self-learning works?

A Space can store skills, and memories in a Notion-like system. You first need to connect a session to Space to enable the learning process:

# Step 1: Create a Space for skill learning space = client.spaces.create() print(f"Created Space: {space.id}") # Step 2: Create a session attached to the space session = client.sessions.create(space_id=space.id) # ... push the agent working context

The learning happens in the background and is not real-time (delay around 10-30s).

What Acontext will do in the background:

graph LR A[Task Completed] --> B[Task Extraction] B --> C{Space Connected?} C -->|Yes| D[Queue for Learning] C -->|No| E[Skip Learning] D --> F[Extract SOP] F --> G{Hard Enough?} G -->|No - Too Simple| H[Skip Learning] G -->|Yes - Complex| I[Store as Skill Block] I --> J[Available for Future Sessions] 
Loading

Eventually, SOP blocks with tool-call pattern will be saved to Space. You can view every Space in the Dashboard:

A Space Demo

A Space Demo

Search Skills from a Space 📖

To search skills from a Space and use them in the next session:

result = client.spaces.experience_search( space_id=space.id, query="I need to implement authentication", mode="fast" )

Acontext supports fast and agentic modes for search. The former uses embeddings to match skills. The latter uses an Experience Agent to explore the entire Space and tries to cover every skill needed.

The return is a list of sop blocks, which look like below:

{ "use_when": "star a github repo", "preferences": "use personal account. star but not fork", "tool_sops": [ {"tool_name": "goto", "action": "goto the user given github repo url"}, {"tool_name": "click", "action": "find login button if any, and start to login first"}, ... ] }

🔍 Document

To understand what Acontext can do better, please view our docs

❤️ Stay Updated

Star Acontext on Github to support and receive instant notifications

click_star

🤝 Stay Together

Join the community for support and discussions:

🌟 Contributing

📑 LICENSE

This project is currently licensed under Apache License 2.0.

🥇 Badges

Made with Acontext Made with Acontext (dark)

[![Made with Acontext](https://assets.memodb.io/Acontext/badge-made-with-acontext.svg)](https://acontext.io) [![Made with Acontext](https://assets.memodb.io/Acontext/badge-made-with-acontext-dark.svg)](https://acontext.io)