autourgos-memory

Base memory interfaces for Autourgos agents — the foundation package. It defines the abstract interfaces (BaseMemory, BaseRetriever, MemoryMessage, Document) that every concrete memory implementation uses.

from autourgos_memory import RuntimeShortTermMemory  # requires autourgos-buffer-memory installed
from autourgos_agent import Agent
from autourgos_openaichat import OpenAIChatModel

my_llm = OpenAIChatModel(model="gpt-4o-mini")
memory = RuntimeShortTermMemory(max_messages=20)
agent  = Agent(llm=my_llm, memory=memory)

Features

• Abstract interfaces: BaseMemory (short-term conversational), BaseRetriever (relevance-scored recall), MemoryMessage, Document
• Soft re-exports: concrete backends resolve from autourgos_memory directly if their own package is installed — RuntimeShortTermMemory, ConversationBufferMemory, LocalShortTermMemory, SQLiteMemory, KeywordRetriever, KeywordMemory, SimpleSemanticRetriever, HierarchicalSemanticMemory, SummaryBufferedMemory, TokenBufferedMemory, VectorMemory, VectorRetriever, Episode, EpisodicMemory
• Zero required dependencies — install only the concrete backends you actually need

Table of Contents

• Install
• Memory Types at a Glance
• Quick Start
• Base Interfaces
• License

Install

# Base interfaces only
pip install autourgos-memory

# Or install concrete implementations individually
pip install autourgos-buffer-memory      # in-memory ring buffer
pip install autourgos-local-memory       # JSON file + SQLite
pip install autourgos-semantic-memory    # TF-IDF keyword retrieval
pip install autourgos-summary-memory     # LLM-compressed rolling summary
pip install autourgos-token-memory       # token-bounded buffer
pip install autourgos-vector-memory      # local, provider-agnostic embedding recall
pip install autourgos-episodic-memory    # structured task/outcome log

Memory Types at a Glance

Quick Start

RuntimeShortTermMemory is soft re-exported from autourgos_memory — it only resolves if autourgos-buffer-memory is also installed:

pip install autourgos-memory autourgos-buffer-memory autourgos-openaichat

from autourgos_memory import RuntimeShortTermMemory
from autourgos_agent import Agent
from autourgos_openaichat import OpenAIChatModel

my_llm = OpenAIChatModel(model="gpt-4o-mini")  # needs OPENAI_API_KEY set
memory = RuntimeShortTermMemory(max_messages=20)
agent  = Agent(llm=my_llm, memory=memory)
result = agent.invoke("What did I ask you last time?")

Base Interfaces

MemoryMessage

from autourgos_memory import MemoryMessage
from datetime import datetime, timezone

msg = MemoryMessage(role="user", content="Hello", timestamp=datetime.now(timezone.utc))
print(msg.to_dict())
# {"role": "user", "content": "Hello", "timestamp": "2024-..."}

Allowed roles: user, agent, system, tool.

BaseMemory

Implement this to create your own memory backend:

from datetime import datetime
from typing import Optional
from autourgos_memory import BaseMemory, MemoryMessage

class MyCustomMemory(BaseMemory):
    def add_message(self, role: str, content: str, timestamp: Optional[datetime] = None) -> MemoryMessage: ...
    def format_for_llm(self, query: str = None) -> str: ...
    def clear(self) -> None: ...

Only add_message, format_for_llm, and clear are true @abstractmethods. add_user_message/add_agent_message/add_system_message/add_tool_message are concrete defaults built on add_message(role, content, timestamp=None) — implement add_message once and every backend gets all four for free. add_agent_message and format_for_llm also carry a deprecation-shim fallback: each calls through to an older method name (add_ai_message / get_context respectively) if your subclass implements that one instead, emitting a DeprecationWarning. This exists only to keep a memory backend written against the pre-rename API working unchanged.

format_conversation_banner / ROLE_TO_OPENAI

Shared helpers for backends implementing format_for_llm/get_messages:

from autourgos_memory import format_conversation_banner, ROLE_TO_OPENAI

format_conversation_banner(messages, include_timestamps=True)
# "\n--- Previous Conversation Context ---\n[2026-...] user: hi\n--------------------------------------\n"

ROLE_TO_OPENAI  # {"user": "user", "agent": "assistant", "system": "system", "tool": "tool"}

RetrievalAugmentedMemory

Base class for a dual-store memory: a short-term buffer (recent turns, always included) plus a BaseRetriever (older, relevant turns, surfaced only when a query is given). This is the shared shape behind autourgos-semantic-memory's KeywordMemory and autourgos-vector-memory's VectorMemory — subclass it, build your own retriever, and pass both to super().__init__():

from autourgos_memory import RetrievalAugmentedMemory

class MyRetrievalMemory(RetrievalAugmentedMemory):
    def __init__(self, my_retriever, short_term=None, top_k=3):
        super().__init__(short_term=short_term or MyShortTermMemory(), retriever=my_retriever, top_k=top_k)

BaseRetriever

Implement this to plug in your own vector database:

from autourgos_memory import BaseRetriever, Document

class MyVectorDB(BaseRetriever):
    def retrieve(self, query: str, top_k: int = 5) -> list[Document]: ...

Document

from autourgos_memory import Document

doc = Document(content="Paris is the capital of France.", score=0.92, source="wiki")

License

Apache License 2.0, Copyright (c) 2026 Jitin Kumar Sengar