autourgos-local-memory

Disk-backed memory for Autourgos agents. Two classes — a JSON file store and a SQLite store. Memory survives process restarts and can be shared across sessions.

from autourgos_local_memory import SQLiteMemory
from autourgos_agent import Agent
from autourgos_openaichat import OpenAIChatModel

my_llm = OpenAIChatModel(model="gpt-4o-mini")
memory = SQLiteMemory(db_path="./data/agent.db", max_messages=500)
agent  = Agent(llm=my_llm, memory=memory)

Features

• LocalShortTermMemory — JSON file, atomic write (tmp → replace), file-level lock
• SQLiteMemory — WAL-mode SQLite, safer than JSON under concurrent writes, efficient for large histories
• Both implement autourgos_memory.BaseMemory — drop-in for Agent(memory=...)
• ":memory:" for an ephemeral in-process SQLite database (useful for tests)

Table of Contents

• Install
• Classes
• Parameters
• Known Limitations
• License

Install

pip install autourgos-local-memory

Classes

LocalShortTermMemory — JSON file

Persists messages as a JSON array. Safe for multiple threads. Uses atomic write (tmp → replace) and a file-level lock to prevent corruption.

from autourgos_local_memory import LocalShortTermMemory
from autourgos_agent import Agent
from autourgos_openaichat import OpenAIChatModel

my_llm = OpenAIChatModel(model="gpt-4o-mini")
memory = LocalShortTermMemory(file_path="./data/session.json", max_messages=50)
agent = Agent(llm=my_llm, memory=memory)
agent.invoke("Remember: my project deadline is Friday")

# Next session — history is loaded from disk automatically
agent2 = Agent(llm=my_llm, memory=LocalShortTermMemory(file_path="./data/session.json"))
agent2.invoke("When is my deadline?")
# → "Your project deadline is Friday."

SQLiteMemory — SQLite database

WAL-mode SQLite. Safer than JSON for concurrent writes — no external lock file needed. Efficient for large histories.

from autourgos_local_memory import SQLiteMemory

memory = SQLiteMemory(db_path="./data/agent.db", max_messages=500)  # None for unlimited
agent = Agent(llm=my_llm, memory=memory)

Use ":memory:" for an ephemeral in-process database:

memory = SQLiteMemory(db_path=":memory:")

SQLiteMemory supports the context-manager protocol, closing its connection automatically:

with SQLiteMemory(db_path="./data/agent.db") as memory:
    agent = Agent(llm=my_llm, memory=memory)
    agent.invoke("Hello!")
# connection is closed here automatically

Parameters

LocalShortTermMemory

SQLiteMemory

Known Limitations

LocalShortTermMemory's file lock is timeout-based (a lock file plus a wait deadline), not an OS-level advisory lock. If one process holds the lock longer than lock_timeout_seconds (e.g. due to slow disk I/O), a second process can end up believing the lock is stale and write concurrently, risking corruption. For high-concurrency multi-process use, prefer SQLiteMemory instead — it uses WAL-mode SQLite, which handles concurrent writers safely without relying on a timeout.

License

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