MemoryOS Agent

A MemGPT-inspired long-term memory agent built with Python, FastAPI, Streamlit, SQLite, and the OpenAI API.

MemoryOS Agent manages durable memories across conversations: user profile facts, preferences, episodic events, semantic knowledge, and tool-use preferences. It can retrieve relevant memories before answering, write useful memories after a turn, merge duplicates, forget matching memories, export user memory, and evaluate memory behavior offline.

Note

This is an independent implementation inspired by MemGPT-style virtual context management. It is not an official implementation and is not affiliated with the MemGPT authors.

Why MemoryOS Agent

• Long-term memory: core, episodic, semantic, and tool memories are stored across sessions.
• OpenAI API first: generation uses the OpenAI API when OPENAI_API_KEY is configured.
• No Ollama dependency: local fallback exists only so tests and demos run without API spend.
• Memory lifecycle: write, retrieve, update, merge, forget, list, delete, and export memory.
• Privacy controls: sensitive facts are flagged and can require approval before saving.
• Evaluation: offline metrics check recall, precision, forgetting accuracy, and update tracking.

See it in action

$ python demo.py

User: Remember that I prefer concise technical answers with implementation details.
Agent: I can save that preference as core memory.

User: What do you remember about my AI career goal?
Agent: I found relevant memory: your goal is to become an LLM Engineer focused on agents and RAG.

User: Forget my preference for concise technical answers.
Agent: I forgot 1 matching memories.

Architecture

flowchart LR
    U["User message"] --> S["Memory search"]
    S --> C["Context assembly"]
    C --> O["OpenAI API"]
    O --> R["Memory-aware answer"]
    U --> P["Memory proposal policy"]
    P --> G{"Sensitive?"}
    G -->|"no"| W["Write / merge memory"]
    G -->|"yes"| A["Approval gate"]
    U --> F{"Forget request?"}
    F -->|"yes"| D["Soft-delete matches"]
    W --> DB["SQLite memory store"]
    D --> DB
    DB --> S

Loading

Quick start

git clone https://github.com/PRINCE2-AI/memoryos-agent.git
cd memoryos-agent
python -m venv .venv

Windows PowerShell:

.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
Copy-Item .env.example .env

macOS/Linux:

source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env

Set your OpenAI key in .env:

OPENAI_API_KEY=your-openai-api-key
MEMORYOS_MODEL=gpt-4.1-mini

Important

MemoryOS Agent is API-first and uses the OpenAI API when OPENAI_API_KEY is configured. It does not require Ollama. The local fallback exists only so tests and demos can run without API spend.

Run

API:

uvicorn app.api:api --reload

Dashboard:

streamlit run app/ui.py

Demo:

python demo.py

Tests:

pytest -q

Memory operations

Operation	What it does
Search	Retrieves relevant active memories for a user message
Write	Saves durable facts, preferences, goals, and workflow hints
Merge	Updates similar memories instead of creating noisy duplicates
Forget	Soft-deletes matching memories on explicit user request
Export	Returns all active/deleted memory records for a user
Evaluate	Scores recall, precision, forgetting accuracy, and update tracking

API

Endpoint	Purpose
GET /health	Check API, model, and database status
POST /chat	Run a memory-aware chat turn
POST /memories/search	Search user memories
GET /memories/{user_id}	List user memories
DELETE /memories/{memory_id}	Soft-delete one memory
GET /memories/{user_id}/export	Export user memory
POST /evaluate/{user_id}	Run offline memory evaluation

Configuration

Start from .env.example:

Variable	Default	Purpose
OPENAI_API_KEY	empty	OpenAI API key for live generation
MEMORYOS_MODEL	gpt-4.1-mini	Chat model used by the OpenAI adapter
MEMORYOS_EMBEDDING_MODEL	text-embedding-3-small	Reserved for vector-memory upgrades
MEMORYOS_DB_PATH	data/memoryos.db	SQLite memory store path
MEMORYOS_MEMORY_TOP_K	6	Maximum retrieved memories per turn
MEMORYOS_AUTO_SAVE	true	Default auto-save behavior
MEMORYOS_REQUIRE_SENSITIVE_APPROVAL	true	Gate sensitive memory writes

Evaluation

The offline evaluator is inspired by memory-agent benchmarks:

• Recall: saved memories can be retrieved by their summaries.
• Precision: top retrieved memory is relevant to the query.
• Forgetting accuracy: soft-deleted memories stay deleted.
• Update accuracy: updated memories are tracked correctly.

Project layout

memoryos-agent/
|-- app/
|   |-- api.py          # FastAPI app
|   |-- engine.py       # Memory-aware chat workflow
|   |-- llm.py          # OpenAI API adapter
|   |-- storage.py      # SQLite memory store
|   |-- policies.py     # Write/forget/approval policies
|   |-- safety.py       # Sensitive-memory detection and masking
|   |-- evaluation.py   # MemoryAgentBench-style metrics
|   `-- ui.py           # Streamlit dashboard
|-- docs/
|-- tests/
|-- demo.py
|-- .env.example
`-- requirements.txt

Safety boundaries

MemoryOS Agent masks common emails, phone numbers, and secret-like strings in generated context. It also flags sensitive memory candidates so applications can require approval before saving them.

Warning

These controls are guardrails, not a compliance system. Do not store private, regulated, or production-sensitive user data without consent, encryption, access control, and retention policies.

Roadmap

• Add OpenAI embeddings for semantic memory search.
• Add Qdrant/ChromaDB vector memory backend.
• Add LangGraph-native memory workflow nodes.
• Add human approval UI for sensitive memory candidates.
• Add benchmark scripts for long-horizon memory tasks.
• Add hosted screenshots and a short demo GIF.

Resume bullets

• Built a MemGPT-inspired MemoryOS Agent using FastAPI, Streamlit, SQLite, and the OpenAI API to manage core, episodic, semantic, and tool memories across sessions.
• Implemented memory retrieval, auto-write policies, duplicate memory merging, selective forgetting, sensitive-memory approval gates, and exportable memory records.
• Added offline MemoryAgentBench-style evaluation for memory recall, retrieval precision, forgetting accuracy, and update tracking with CI-backed tests.