aurra-langchain 0.1.0

LangChain integration for Aurra — memory infrastructure with citations, audit trails, and bi-temporal versioning

aurra-langchain

LangChain integration for Aurra - memory infrastructure for AI agents.

Drop-in BaseChatMessageHistory that gives your LangChain agents:

• Bi-temporal versioning - memories know what was true, when, and who superseded them
• Citation-grounded retrieval - every retrieved fact carries its source
• Multi-tenant isolation - scope memories per-user without index sprawl
• Auto-supersession - Aurra's classifier detects when a new fact replaces an old one

Targets LangChain 1.0+ (uses the RunnableWithMessageHistory pattern).

Installation

pip install aurra-langchain

Usage

from aurra_langchain import AurraChatMessageHistory
from langchain_core.runnables.history import RunnableWithMessageHistory
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
from langchain_anthropic import ChatAnthropic

# Wire up history backed by Aurra
def get_session_history(session_id: str):
    return AurraChatMessageHistory(
        api_key="aurra_...",
        session_id=session_id,
        tenant_id="acme-corp",  # optional
    )

prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a helpful assistant with memory."),
    MessagesPlaceholder("history"),
    ("human", "{input}"),
])

chain = prompt | ChatAnthropic(model="claude-haiku-4-5-20251001")

with_history = RunnableWithMessageHistory(
    chain,
    get_session_history,
    input_messages_key="input",
    history_messages_key="history",
)

# Each turn writes to Aurra automatically
with_history.invoke(
    {"input": "My favorite coffee is Stumptown."},
    config={"configurable": {"session_id": "user-42-conv-7"}},
)

Direct API

You can also use it standalone, without RunnableWithMessageHistory:

history = AurraChatMessageHistory(
    api_key="aurra_...",
    session_id="user-42-conv-7",
)
history.add_user_message("My favorite coffee is Stumptown.")
history.add_ai_message("Got it.")
print(history.messages)  # list of messages, oldest first

Configuration

Param	Type	Default	Description
api_key	str	required	Your Aurra API key (from app.aurra.us)
session_id	str	required	Conversation identifier (groups extracted memories)
tenant_id	str	None	Multi-tenant scope (optional)
base_url	str	https://api.aurra.us	Override for self-hosted/staging
auto_supersede	bool	None	Per-key default if None
max_messages_returned	int	50	Cap on history.messages length

What gets stored

Each add_user_message / add_ai_message call buffers the turn. When both sides of an exchange are present, the pair is sent to Aurra's /agent/memories endpoint in messages mode. Aurra's extractor LLM atomizes the exchange into individual factual memories.

The messages getter pulls memories back as HumanMessage / AIMessage objects in chronological order, reconstructed from each memory's original_message field.

Lossiness note

Aurra is a fact store, not a verbatim message store. Round-tripping messages is approximate: original_message is preserved up to 500 chars per turn, and extracted memories may have refined wording. If you need 100% faithful conversation replay, use a different LangChain backend.

Limitations (v0.1.0)

• Streaming not yet supported (PRs welcome)
• Tool integration deferred to v0.2.0
• Retriever class (separate from history) deferred to v0.2.0
• The legacy BaseMemory pattern (LangChain 0.x) is not supported - use RunnableWithMessageHistory with AurraChatMessageHistory instead

License

MIT.