# Acontext: agent memory stored as skill files you can read and edit

> Acontext is an open-source memory layer that distills agent runs into Markdown skill files instead of embeddings. It suits teams that want inspectable, portable memory, and it is the wrong tool if you need automatic recall without giving the agent a tool loop.

**memodb-io/Acontext** — Agent Skills as a Memory Layer

- Repository: https://github.com/memodb-io/Acontext
- Website: https://acontext.io
- Stars: 3,695 · Forks: 334
- Language: JavaScript
- License: Apache-2.0
- Published: 2026-09-09 · Updated: 2026-09-09 · Language: en
- Canonical page: https://hysenlabs.com/projects/memodb-io-acontext

## The problem Acontext picks: memory nobody can read

Most agent memory systems store state as vectors. You can query them and you can measure recall, but you cannot open one and see why the agent believes what it believes. When the agent repeats a mistake, the debugging path runs through an embedding index rather than a file. Acontext takes the opposite position. Its README states the project is a skill memory layer that captures learnings from agent runs and stores them as agent skill files, described as files you can read, edit, and share across agents, LLMs, and frameworks. The audience is narrow and identifiable: developers building agents that complete repeatable tasks, who want the agent to reuse what worked last time and who are willing to inspect the artifact. If your memory needs are conversational continuity rather than task learning, this framing buys you little.

## Store and recall: two flows, one file format

The README splits the mechanism into two flows. The store flow starts with session messages, optionally including tool calls and artifacts. Tasks are extracted from the message stream automatically, or inferred from explicit outcome reporting. When a task is marked done or failed, that outcome triggers learning. An LLM pass then distills the conversation and execution trace into what worked, what failed and user preferences. A skill agent decides whether to write into an existing skill or create a new one, following the schema defined in SKILL.md. The recall flow is deliberately not a search. The agent gets Skill Content Tools, named in the README as get_skill and get_skill_file, and calls them when it needs something. The README calls this progressive disclosure with the agent in the loop, and states plainly that there is no embedding search and no semantic top-k retrieval. That is the whole architecture: an LLM writes files, an agent reads files. The trade-off is visible in the design. Retrieval quality now depends on the agent's judgement about what to fetch, not on a similarity score.

## Installing the CLI and running a first self-hosted stack

The README gives two paths. The hosted path is to claim credits at acontext.io and go through onboarding to get an API key starting with sk-ac. The self-hosted path uses acontext-cli, which the README says is intended for a quick proof-of-concept. Install it with the shell script, then create a directory and bring the server up.

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

The README states you need Docker installed and an OpenAI API key. By default Acontext uses gpt-4.1, and the README warns that your LLM has to support tool calling.

```bash
mkdir acontext_server && cd acontext_server
acontext server up
```

According to the README, that command creates or reuses .env and config.yaml, and creates a db folder to persist data. Once it finishes, two endpoints are available: the API base URL at http://localhost:8029/api/v1 and the dashboard at http://localhost:3000/. For application code, install the Python SDK.

```bash
pip install acontext
```

Client construction is shown for both cloud and self-hosted use, with the cloud form reading ACONTEXT_API_KEY from the environment. The README points to the TypeScript SDK quickstart for the npm package @acontext/acontext. A first real use is to point an existing agent at these tools, let it finish a task, then open the resulting skill file and read what the distillation pass decided to keep.

## Where the file-based design costs you

The same property that makes skills inspectable makes them expensive. Every finished task can trigger an LLM distillation pass, and the README describes that pass as running over the conversation and execution trace. There is no documented way to turn distillation off, so a high-volume agent pays for a model call per completed task on top of the calls it already made. Recall is the second constraint. Because retrieval is tool use rather than search, an agent that never calls get_skill learns nothing from the stored files, and the README does not describe a fallback that injects relevant skills automatically. Third, the README says tasks are extracted automatically or inferred from explicit outcome reporting, but it does not document how automatic detection decides a task has ended. If your agent runs long, open-ended sessions with no clear completion signal, the trigger for learning may never fire. Acontext is also a poor fit when memory must be shared across many tenants with per-record access control, since the unit of storage is a file rather than a row.

## How it differs from vector memory tools such as Memobase

Memobase appears in the related searches around this project, and the contrast is instructive rather than competitive. A vector-based memory service typically extracts facts from conversations, embeds them, and returns the top matches for a query. The application does not decide what to retrieve; the index does, and the retrieved text is opaque until you render it. Acontext inverts both halves. Storage is a Markdown file per skill, so the schema is something you author in SKILL.md rather than something the service imposes. Retrieval is a tool call the agent makes, so the agent's reasoning selects the context instead of a similarity threshold. The README also stresses portability: skill files export as ZIP, and the project states there is no re-embedding or migration step when you move them elsewhere. The cost of that portability is that you now own the schema design and the agent's tool-use behaviour. A vector store gives you recall without asking the agent to cooperate; Acontext gives you legibility in exchange for that cooperation.

## Maintenance, licence and what you are signing up for

The repository is not archived, and the last push was on 2026-07-14, which is recent enough that the project is still moving. The most recent tagged releases are ui/v0.1.14, sdk-ts/v0.1.21 and package-claude-code/v0.1.3, all dated 2026-04-08, so the version numbers are early and the interfaces around them should be treated as unsettled. The licence is Apache-2.0, which permits commercial use and modification and includes a patent grant; this is a summary of the identifier, not legal advice, and you should read the LICENSE file and your own obligations before shipping. Upgrade cost is concentrated in two places. The SDK packages are versioned separately from the UI and the Claude Code package, so a change in one does not imply a change in the others. And because your memory lives in files whose layout you define, a schema change is your migration, not the project's. The repository layout includes charts/, dashboard/, docs/ and src/, so a self-hosted deployment has more moving parts than a single binary.

## Conclusion

Adopt Acontext if you already run agents that complete discrete tasks and you want memory a human can open, diff and correct, especially when the same skills must move between Claude, LangGraph or another framework. Skip it if your recall path has to work without a tool-calling round trip, or if you cannot accept an LLM pass over every finished task, since distillation is the mechanism and there is no documented switch that turns it off. Before committing, verify three things against the current docs: the exact schema rules Acontext enforces inside SKILL.md, how the system decides a task has completed when your agent does not report an outcome, and whether the self-hosted stack's gpt-4.1 default can be pointed at a model you already pay for.

## FAQ

### How do I use Acontext with a React app?

The README does not document a React integration. It describes a Python SDK installed with pip install acontext and a TypeScript SDK published as @acontext/acontext, and says the snippets in the quickstart use Python. A React front end would talk to the Acontext API at http://localhost:8029/api/v1 when self-hosted, or through the hosted service.

### How do I use Acontext?

Claim credits at acontext.io for the hosted path, or install the CLI and run acontext server up for a self-hosted backend. Then install an SDK, initialize a client with your API key, and give your agent the get_skill and get_skill_file tools so it can fetch skill content.

### What is agentic context engineering in relation to Acontext?

The README does not use that term. It describes the closest equivalent as progressive disclosure: the agent calls get_skill and get_skill_file to fetch what it needs, and the README states retrieval is by tool use and reasoning rather than semantic top-k search.

### What are Anthropic agents, and does Acontext work with them?

The README does not define Anthropic agents. It does ship a package-claude-code release and gives a Claude Code install prompt that reads https://acontext.io/SKILL.md, and it states skill memories are Markdown files usable with Claude, LangGraph, AI SDK or anything that reads files.

### How does the AI context window relate to how Acontext stores memory?

Acontext does not push stored memory into the context window automatically. The README states the agent decides what it needs and calls get_skill or get_skill_file, so skill content appears in context only after that tool call.

### What is context for dummies in Acontext's terms?

In Acontext, the stored context is a set of Markdown skill files. The README describes them as files you can read, edit and share, updated by an LLM distillation pass after a task is marked done or failed, with the structure defined in SKILL.md.

## Sources

- [License: Apache-2.0](https://github.com/memodb-io/Acontext/blob/main/LICENSE)
- [memodb-io/Acontext on GitHub](https://github.com/memodb-io/Acontext)
- [Project website](https://acontext.io)
- [README](https://github.com/memodb-io/Acontext/blob/main/README.md)
- [Releases](https://github.com/memodb-io/Acontext/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/memodb-io-acontext