agent-memory

agent-memory adds persistent memory so an agent can remember facts, learn from experience, and track entities across sessions instead of starting cold each time. The entity-tracking angle is the useful twist — it's not just a flat fact store, it keeps relationships between recurring people/things, which is what makes retrieval feel like memory rather than keyword search. As with any memory layer, pair it with a retention/eviction policy so stale facts don't silently outlive their usefulness.

Use case: Giving a long-running assistant durable, entity-aware recall across sessions.

# Getting started with agent-memory This skill gives an agent a durable memory store backed by a local database file. There is no service to run, which is the main reason to pick it over a hosted memory product. ## Install ```bash clawdhub install agent-memory ``` ## Basic use ```python from src.memory import AgentMemory mem = AgentMemory() # defaults to ~/.agent-memory/memory.db # durable facts mem.remember("Backups are pruned after 30 days", tags=["ops", "retention"]) # lessons need all four fields to be worth storing mem.learn( action="Retried a failed upload immediately", context="flaky outbound network during a batch job", outcome="negative", insight="Immediate retries fail too; add backoff before retrying", ) facts = mem.recall("backup retention") lessons = mem.get_lessons(context="outbound network failures") mem.track_entity("Acme", "organisation", {"role": "customer"}) ``` ## Wiring it into the session lifecycle The library only becomes memory once the agent reads and writes it on a schedule. Two hook points do most of the work: - At session start, load recent lessons and recall facts for the current task before planning. - At session end, extract durable facts and record one lesson per notable failure. Put that protocol in the agent's standing instructions so it survives across runs. ## Choosing a path The default path sits under the home directory. On a container or a fresh virtual machine that directory is often ephemeral, so pass an explicit path on a mounted volume or memory resets silently between runs. ## Tips - Store one lesson per failure with a specific insight; an insight like "be more careful" cannot be recalled or acted on later. - Gotcha: the default database path lives in the home directory, which is frequently wiped in containers, so point at a mounted volume. - Tag facts tightly enough to be findable and loosely enough to still match a later query. - Load lessons at start of a session, not only at the end; memory that is only written is a log, not memory. - Track long-lived entities such as people, projects and systems so later sessions inherit their context.