A memory store your agent writes to itself

What it is

Memory the agent decides to keep#

Most agents forget everything when a conversation ends. wenchang gives the agent a small set of tools for writing and reading memory. Nothing outside the agent decides what gets saved. The agent notices a character detail, a plot decision, or a style preference, and writes it down.

Say an author is writing a novel with an assistant built on wenchang. The author mentions that the protagonist, Lin Qiao, has grey eyes and grew up in a river town. The agent saves it in a file called project/p-ninth-examination/characters/lin-qiao.md:

description: Lin Qiao, the protagonist
aliases: Qiao
---
- [stated] Has grey eyes.
- [stated] Grew up in Yunmen, a river town.

Weeks later, in a new conversation, the author asks for a scene with Lin Qiao. The agent reads its index, opens that file, and gives her grey eyes. If the author changes their mind, the agent edits that one line.

wenchang does not decide what is worth keeping. A prompt that ships with the library tells the agent how to decide, and you can change that prompt. See Customizing the prompts.

How it works

How it works#

The agent starts from an index#

At the start of each session the agent calls get_memory_index(). It gets one entry for every file it has written: scope, area, name, version, a one-line description, and aliases. It does not get file contents. It reads the descriptions, decides which files matter for the current conversation, and opens only those.

// get_memory_index()
{
  "entries": [
    {
      "scope": "project", "area": "characters", "name": "lin-qiao",
      "version": "3",
      "description": "Lin Qiao, the protagonist",
      "aliases": ["Qiao"]
    },
    {
      "scope": "project", "area": "timeline", "name": "main-timeline",
      "version": "1",
      "description": "Order of events in the novel",
      "aliases": ["chronology", "timeline"]
    }
  ],
  "capped": []
}

Real entries also carry sources, and last_updated. If the index gets too big, it is cut at a size limit and the agent lists the rest with list_prefix. There is no search over file contents. Descriptions and aliases are how the agent finds things, so the agent keeps them up to date as it writes.

The agent organizes its own files#

The agent has seven tools: get_memory_index, read_file, list_prefix, write_file, append_line, replace_fact, and delete_file. Each fact is one line. The agent can add a line, change a line, or drop one. It can rewrite a file, create one, or delete one. It can change a file's description and aliases whenever it writes.

The library sets no schema. The agent decides how to split memory into files, which file a fact belongs in, and what to delete when a fact stops being true. The shipped prompt pushes it toward one file per subject, toward appending to an existing file instead of creating a duplicate, and toward removing a fact completely when the user asks it to forget.

Scopes and areas#

Every file path has this shape:

{scope}/{entity_id}/{area}/{name}.md
project/p-ninth-examination/characters/lin-qiao.md

A scope says who can see a file. You define the scopes. A common set is user (private to one person), project (shared by a team), and organization (shared by everyone, writable only by admins). For a novel, user is the author's own preferences, project is the manuscript, and organization is the publisher. The entity ID says whose copy of that scope it is: u-tianlong is one author, p-ninth-examination is one manuscript.

An area is a kind of information inside a scope, such as characters, plot, timeline, or style in a manuscript. You can seed the areas you care about in the prompt, for example "project: characters, plot, timeline, style". Or you can tell the agent to choose its own. Either way it can add areas by writing a file in a new one.

Every scope also has a system/ area. You fill it with curated content. The agent can read it and can never change it.

How you use it

How you use it#

wenchang is a library. You put its tools in front of your agent in one of three ways, all sharing the same store, identity rules, and prompt. Choose an integration path compares them.

The quickest start is a stdio server in Claude Code:

1. Install it and create a GCS bucket for memory files. Quickstart
2. Write the server script. It picks the storage, says who the caller is, and builds the MCP server:

   server = build_server(
       slots=slots,  # your prompt text
       client=InProcessClient(MemoryStore(GcsStorage(bucket))),
       resolver=resolver,  # who is calling, and with which scopes
       policy=policy,  # which roles may write which scopes
       credentials_from_context=credentials_from_context,
       source="inkwell-web",
   )
   server.run("stdio")
   

   Quickstart
3. Register it with your MCP client. For Claude Code, claude mcp add memory -- python server.py. Quickstart
4. Tune the prompts. Four text slots tell the agent what your product is, which scopes exist, and which areas to start with. Customizing the prompts
5. Plug in your own auth when more than one person uses the server. Identity and multi-tenant auth

Scope of the library

What wenchang is and is not#

wenchang provides the primitives for agent memory. It is not a hosted service and not a complete product.

Version 0.1.1, MIT license, Python 3.11 or newer. See Status and compatibility for known limits.