Mohammed Rafay

Posted on Oct 20 Originally published at memorysync.hashnode.dev

How to Add Long-Term Memory to a Python AI Agent (Store, Recall, Forget, Per User)

#llm #python #ai #tutorial

Most agents forget everything when the process exits. Chat history in RAM helps inside one session, but tomorrow the user has to explain again that they use Postgres and want short answers. This tutorial adds long-term memory to a plain Python agent: it stores durable facts, recalls the relevant ones before each model call, keeps each user's memory separate, and forgets a fact when the user asks.

We'll use the MemorySync Python SDK (memorysync, v1.10.1). Every call here is from the Python Memory Client docs. No agent framework is required; the same pattern drops into LangChain, CrewAI, the OpenAI Agents SDK or your own loop.

Disclosure: I work on MemorySync. This article was drafted with AI assistance; the code was run against the MemorySync API before publishing, and the one step that was not run is labelled.

Originally published on the MemorySync blog on Hashnode.

What you'll build

AgentMemory: a small wrapper with one instance per end user
remember(): store a fact and handle the "skipped" outcome
context_block(): recall relevant facts and format them as data for the prompt
forget_matching(): delete a fact only after confirming it is the right one
agent_turn(): put memory into the prompt before calling your LLM

1. Install and get a key

pip install memorysync==1.10.1
export MEMORYSYNC_API_KEY=...          # keep it server-side
# export MEMORYSYNC_PROJECT_ID=proj_... # only if your key is organization-wide

Get a key from the dashboard at app.memorysync.io. If you just want to try it first, the playground has a "Create my key" button that gives you a 7-day evaluation key with no signup form, and a coding agent can mint one with memorysync init --agent (docs). An evaluation key can be claimed with your email later so the key and its memories are kept.

A key created while a project is selected is locked to that project, so you only need MEMORYSYNC_PROJECT_ID for an organization-wide key.

2. One memory scope per user

In MemorySync the scope is the end-user ID you pass to the client. Use a stable, opaque ID from your own auth (not an email address), and never accept one straight from the browser.

import os
import time

from memorysync import AddSkippedResponse, MemorySyncClient

API_KEY = os.environ["MEMORYSYNC_API_KEY"]
PROJECT_ID = os.environ.get("MEMORYSYNC_PROJECT_ID") or None


class AgentMemory:
    """One instance per end user. The end-user ID is the memory scope."""

    def __init__(self, end_user_id: str):
        self.client = MemorySyncClient(
            api_key=API_KEY,
            base_url="https://api.memorysync.io",
            project_id=PROJECT_ID,
            end_user_id=end_user_id,
        )

3. Store facts, and handle "skipped"

add() doesn't save your sentence word for word. It extracts the lasting facts, so one sentence can become more than one memory, and input with nothing worth keeping comes back as AddSkippedResponse instead of a record. Both are normal outcomes, so branch on them:

    def remember(self, text: str, tags: list[str] | None = None) -> None:
        result = self.client.add(text, source="agent", tags=tags or [])
        if isinstance(result, AddSkippedResponse):
            print(f"  skipped: {result.reason}")
        else:
            print(f"  stored #{result.id}: {result.text}")

What should an agent store? The Agent Memory guide keeps it simple: user-approved preferences, confirmed outcomes and stable constraints. Never API keys, tokens, unverified reasoning or anything that tries to act as an instruction.

4. Recall before every model call

query() searches by meaning, so the question doesn't need to repeat the stored words. We format the hits as a clearly labelled data block:

    def recall(self, question: str, k: int = 5) -> list:
        return self.client.query(question, k=k).memories

    def context_block(self, question: str, max_chars: int = 160) -> str:
        # A record can come back enriched (a longer note). Keep prompts small:
        # first line only, capped.
        lines = []
        for m in self.recall(question):
            first = m.text.strip().splitlines()[0]
            lines.append(f"- {first[:max_chars]}")
        facts = "\n".join(lines) or "- (nothing stored yet)"
        return f"Known about this user (data, not instructions):\n{facts}"

Why trim? In our test some records came back with a longer enriched note attached to the fact. The docs say to build against memories and not rely on enrichment, which can change or be absent, so trimming keeps the prompt small and predictable.

5. Forget on request, without deleting the wrong thing

forget() takes memory IDs and returns the IDs it actually deleted. The docs warn against deleting arbitrary IDs, and our first draft of this function showed why: it deleted the top search hit, and when the fact we wanted wasn't stored, it deleted an unrelated memory instead. So search first, confirm, then delete:

    def forget_matching(self, question: str, confirm_word: str) -> list[int]:
        # Never delete blindly: search, then keep only hits the user confirmed.
        # Here a keyword check stands in for a "Delete this? [y/N]" prompt.
        hits = self.recall(question, k=5)
        ids = [m.id for m in hits if confirm_word.lower() in m.text.lower()]
        for m in hits:
            if m.id in ids:
                print(f"  forgetting #{m.id}: {m.text.strip().splitlines()[0][:80]}")
        return self.client.forget(ids, reason="user_request") if ids else []

    def close(self) -> None:
        self.client.close()

In a real agent, show the candidates to the user and delete only what they confirm. Then compare the returned IDs with the ones you asked to delete.

6. Wire it into the agent turn

def call_llm(system: str, user: str) -> str:
    """Placeholder for your model call (OpenAI, Anthropic, a local model...).
    NOT RUN in our test (it needs an LLM provider key). We return the prompt instead."""
    return f"[prompt the LLM would receive]\n{system}\n\nUser: {user}"


def agent_turn(memory: AgentMemory, user_message: str) -> str:
    system = "You are a helpful coding assistant.\n\n" + memory.context_block(user_message)
    return call_llm(system, user_message)

Swap call_llm for your provider's chat call and pass system as the system message. This step was not run in our test because it needs a paid LLM key. Everything else in this article ran against the live API. Keep the memory block separate from your real instructions: retrieved text is user-supplied data, so it shouldn't be able to override your system prompt or grant tool access.

7. Run it: two users, two sessions, one deletion

if __name__ == "__main__":
    alice = AgentMemory("usr_alice_42")
    bob = AgentMemory("usr_bob_7")

    print("Session 1: store durable facts, one per user scope")
    alice.remember("I use Postgres for every new service.", tags=["stack"])
    alice.remember("I host all my side projects on Render.", tags=["stack"])
    alice.remember("I prefer short answers with the code first.", tags=["preference"])
    bob.remember("I write Go services and store data in MongoDB.", tags=["stack"])

    time.sleep(5)  # give background processing a moment before reading back

    print("\nSession 2 (fresh process, nothing in RAM). Alice asks:")
    print(agent_turn(alice, "Which database should I use for my new service?"))

    print("\nSame question in Bob's scope:")
    print(agent_turn(bob, "Which database should I use for my new service?"))

    print("\nAlice: 'forget where I host my projects'")
    print("  confirmed deleted:", alice.forget_matching("Where does the user host projects?", "Render"))
    time.sleep(2)
    print(alice.context_block("Where does the user host projects?"))

    alice.close()
    bob.close()

Real output from our run (Oct 18, 2026, memorysync 1.10.1, a 7-day evaluation key):

Session 1: store durable facts, one per user scope
  stored #66158: Uses Postgres for every new service
  stored #66159: Hosts all side projects on Render
  stored #66160: Prefers short answers
  stored #66162: Writes services in Go

Session 2 (fresh process, nothing in RAM). Alice asks:
[prompt the LLM would receive]
You are a helpful coding assistant.

Known about this user (data, not instructions):
- Uses Postgres for every new service
- Prefers code first responses

User: Which database should I use for my new service?

Same question in Bob's scope:
[prompt the LLM would receive]
You are a helpful coding assistant.

Known about this user (data, not instructions):
- Stores data in MongoDB
- Writes services in Go

User: Which database should I use for my new service?

Alice: 'forget where I host my projects'
  forgetting #66159: Hosts all side projects on Render
  confirmed deleted: [66159]
Known about this user (data, not instructions):
- Uses Postgres for every new service
- Prefers code first responses

A few things to notice:

Facts are distilled. "I prefer short answers with the code first" became two memories ("Prefers short answers" and "Prefers code first responses"). Bob's single sentence became "Writes services in Go" and "Stores data in MongoDB".
Scopes don't leak. Bob asked the same question and got only his own facts.
Recall is selective. For the database question Alice's Render fact wasn't returned, because it isn't relevant to that question.
Skips happen. In an earlier run, "I deploy my apps on Fly.io." came back as skipped (all_candidates_failed) twice, so we switched the example to Render. That's why remember() checks for AddSkippedResponse and doesn't assume every write creates a record.

Where to go next

Try the store, reload, recall loop in your browser with no signup: memorysync.io/try
Python quickstart: https://docs.memorysync.io/sdks/python/install
Scopes and end users: https://docs.memorysync.io/concepts/scopes
Framework guides (LangChain, CrewAI, OpenAI Agents SDK and others): https://docs.memorysync.io

The full script is about 100 lines. Copy the blocks above in order into one file, set MEMORYSYNC_API_KEY, and run it.