asmemory — Action-State Memory Engine

Give your agent a time memory: record what happened and what changed, then analyze trends, anomalies, and causality — not just what was said.

Language: English | 简体中文

⭐ If this helps you, a star is the best way to say thanks — it keeps the project visible to others.

What it does

asmemory stores two kinds of typed events, not raw text:

• State — a value of some entity/metric at a point in time (gpu.temperature = 78°C)

• Action — something that happened (agent ran training, operator adjusted a valve)

On top of this memory it provides four analyses:

Related MCP server: CarpeOS MCP Server

Why asmemory

Most memory plugins store conversations or documents, so they answer "what did you say". asmemory stores actions and states, so it answers "what happened, and why":

"Did GPU temperature rise after training started?" → causal "Is my sleep trending down this week?" → trend "Which readings are outliers?" → anomaly

It is the memory layer for the physical and operational world — agents observing themselves, industrial processes, and personal metrics.

Example: agent self-tracking

Record your agent's own actions and resource states, then ask why the GPU got hot:

from asmemory import StateEvent, ActionEvent, MemoryStore, analysis

store = MemoryStore("memory.db")
store.add_state(StateEvent("gpu", "temperature", 78.5, "celsius"))
store.add_action(ActionEvent("agent", "run_training", "qwen3.6", ts=1723500000))

# Did training actually heat the GPU?
causal = analysis.causal_effect(store, "run_training", "gpu", "temperature")
print(causal["before_mean"], "->", causal["after_mean"], f"(Δ={causal['delta']})")

Real output (24h simulated agent, 72 states + 20 actions):

【因果】run_training → gpu.temperature:  45.3 → 78.7  (Δ=33.4, up)   ← significant
【因果对照】git_commit → gpu.temperature: 53.7 → 56.4  (Δ=2.7, up)    ← no effect
【异常】ram.usage: 1 outlier (z=-2.4)

The engine cleanly separates real causality (training) from coincidence (git commits) — no LLM guessing involved, just time-series math.

Example: industrial monitoring → DataLens

Air-separation plant: oxygen purity (monitored metric) vs. valve opening (control action). asmemory remembers the causality, then exports to DataLens for over-control optimization:

from asmemory.export import export_datalens

export_datalens(store, entity="oxygen", metric="purity",
                action_verb="valve_adjust",
                pollutant="氧纯度", regulator="导叶开度",
                regulatory_limit=99.5)
# → data_datalens.csv + data_datalens.config.json

Real output (240 min, 240 states + 240 actions):

【因果】valve_adjust → oxygen.purity: Δ=0.0009 (up)
✅ CSV → data_datalens.csv          (时间,指标值,控制量,整点标记)
✅ config → data_datalens.config.json (pollutant/regulator/limit)

Open data_datalens.csv in DataLens to visualize the "still over-controlling in the safe zone" savings space.

Tools

Seven MCP tools, exposed to the model as mcp__asmemory__<tool>:

Installation

The server runs from the asmemory-mcp command (or an absolute path via ASMEMORY_MCP_PATH). Install the command first, then register the MCP bridge with DSH.

1. Install the asmemory-mcp command:

   pip install .

   (Or skip the install and set ASMEMORY_MCP_PATH=/path/to/bin/asmemory-mcp instead.)

2. Launch DSH with the plugin patch:

   dsh web --patch "$PWD/cordis.yml"

   (Once published, you can also run dsh plugin add dsh-plugin-asmemory.)

3. Done. The server is a single stdio process using only the Python 3.10+ standard library.

Persistence defaults to ~/.asmemory/memory.db (override with ASMEMORY_DB_PATH).

Verified

The full loop is tested end-to-end on a real DSH instance (headless profile + a local Qwen3.6 model): the agent called memory_store_state, memory_store_action, and memory_summary, and the events landed in SQLite — exactly the data it was asked to record.

Quick start

python3 examples/demo_agent_self_tracking.py   # agent self-tracking demo
python3 examples/demo_datalens_export.py       # industrial → DataLens export demo

Use cases

• Agent self-tracking — record the agent's own actions and resource states

• Industrial monitoring — process variables and operator actions (air separation, emission control)

• Personal data — sleep, weight, spending, exercise trends

License

MIT — use it, fork it, ship it. And if it earns you a star-shaped reward in return, all the better. ⭐