autourgos-semantic-memory

TF-IDF keyword retrieval memory for Autourgos agents.

Combines a short-term message buffer with a TF-IDF keyword index. When the agent asks for context, relevant past messages are retrieved by keyword similarity and prepended — even if they fell outside the short-term window.

Zero external dependencies. No embeddings, no vector database required.

Install

pip install autourgos-semantic-memory

Quick Start

my_llm below is any chat-model instance, e.g. OpenAIChatModel from autourgos-openaichat (pip install autourgos-openaichat, needs OPENAI_API_KEY set). See that package's README for setup.

Classes

KeywordMemory

Dual-store memory: recent messages in a ring buffer + all messages indexed for TF-IDF retrieval.

from autourgos_semantic_memory import KeywordMemory
from autourgos_react_agent import ReactAgent
from autourgos_openaichat import OpenAIChatModel

my_llm = OpenAIChatModel(model="gpt-4o-mini")
memory = KeywordMemory(top_k=3)  # surface top 3 relevant past messages
agent  = ReactAgent(llm=my_llm, memory=memory)

agent.invoke("The server is running on port 8080")
agent.invoke("The database password is hunter2")
# ... many more messages ...
agent.invoke("What port is the server on?")
# → retrieves the port message from the keyword index even if it left the buffer

KeywordRetriever

Standalone TF-IDF retriever. Plug it into KeywordMemory or use directly with your own memory:

from autourgos_semantic_memory import KeywordRetriever
from autourgos_memory import Document

retriever = KeywordRetriever()
retriever.add_document(Document(content="Paris is the capital of France.", source="wiki"))
retriever.add_document(Document(content="Berlin is the capital of Germany.", source="wiki"))

results = retriever.retrieve("What is the capital of France?", top_k=1)
print(results[0].content)
# → "Paris is the capital of France."

Custom short-term store

from autourgos_semantic_memory import KeywordMemory
from autourgos_local_memory import SQLiteMemory

# Use SQLite as the short-term buffer (survives restarts)
memory = KeywordMemory(
    short_term=SQLiteMemory(db_path="./data/agent.db"),
    top_k=5,
)

Parameters

KeywordMemory

KeywordRetriever

How TF-IDF works here

• Every message is tokenized (lowercase alphanumeric) and indexed.
• IDF weights are computed at query time — so scores stay accurate as more messages are added.
• Cosine similarity ranks results. Only messages with score > 0 are returned.
• Back-compat aliases: SimpleSemanticRetriever = KeywordRetriever, HierarchicalSemanticMemory = KeywordMemory.

Cost note: retrieve() recomputes TF-IDF weights across the whole corpus on each call where the index changed since the last query. This is fine for small-to-medium message stores, but the per-query cost grows with corpus size. If you expect a long-running agent to accumulate many thousands of documents, set max_documents to cap the index size and keep retrieval fast.

Links

• PyPI: https://pypi.org/project/autourgos-semantic-memory/
• GitHub: https://github.com/devxjitin/autourgos-semantic-memory
• Issues: https://github.com/devxjitin/autourgos-semantic-memory/issues

License

MIT — see LICENSE