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.

from autourgos_semantic_memory import KeywordMemory
from autourgos_agent import Agent
from autourgos_openaichat import OpenAIChatModel

my_llm = OpenAIChatModel(model="gpt-4o-mini")
memory = KeywordMemory(top_k=3)
agent  = Agent(llm=my_llm, memory=memory)

Features

• KeywordMemory — dual-store: recent messages in a ring buffer + all messages indexed for TF-IDF retrieval
• KeywordRetriever — standalone TF-IDF retriever, usable on its own or plugged into KeywordMemory
• Zero external dependencies — cosine similarity over TF-IDF weights, computed at query time
• Bounded index — optional max_documents FIFO eviction keeps retrieval fast on long-running agents

Table of Contents

• Install
• Classes
• Custom Short-Term Store
• Parameters
• How TF-IDF Works Here
• License

Install

pip install autourgos-semantic-memory

Classes

KeywordMemory

from autourgos_semantic_memory import KeywordMemory
from autourgos_agent import Agent
from autourgos_openaichat import OpenAIChatModel

my_llm = OpenAIChatModel(model="gpt-4o-mini")
memory = KeywordMemory(top_k=3)  # surface top 3 relevant past messages
agent  = Agent(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.

License

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