Skip to content

About

LangChain + LangGraph memory adapter for Artesian — recall, commit, and session handoff through governed agent memory

Topics

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

artesian-langchain

LangChain + LangGraph memory adapters for Artesian — governed agent memory.

Instead of writing directly to a raw vector store, your LangChain/LangGraph app routes all recall and commit through Artesian's governance layer: qualify-gate (deduplication, scoring), OCF cross-agent session handoff, hybrid retrieval with MMR diversification, and token-savings accounting. This is the value prop: you get structured, auditable memory rather than an uncontrolled append-only store.

Install

pip install artesian-langchain

You also need the artesian CLI installed and reachable on your $PATH:

# via Homebrew (macOS / Linux)
brew install aquifer-labs/tap/artesian

# or download a pre-built binary from
# https://github.com/aquifer-labs/artesian/releases

Verify installation:

artesian doctor

Adapters

Adapter LangChain/LangGraph base class What it does
ArtesianStore langgraph.store.base.BaseStore Long-term memory. Put/search through Artesian qualify-gate + MMR retrieval
ArtesianSaver langgraph.checkpoint.base.BaseCheckpointSaver Thread state checkpoints via OCF session handoff
ArtesianChatMessageHistory langchain_core.chat_history.BaseChatMessageHistory Per-session chat history stored as governed memory records

Usage

1. LangGraph Store (long-term memory)

from artesian_langchain import ArtesianClient, ArtesianStore

# Configure the client — all writes/reads go through the artesian CLI
client = ArtesianClient(
    binary="artesian",      # path or name of the artesian binary
    config="artesian.toml", # path to your artesian config (optional)
    backend="qdrant",       # backend: "files" | "sqlite-vec" | "qdrant"
)

store = ArtesianStore(
    client=client,
    default_scope="shared",   # Artesian memory scope
    agent_id="my-agent",
    mmr=True,                 # Enable MMR diversification on search
)

# Store a memory record (goes through Artesian qualify-gate)
store.put(("user", "prefs"), "ui", {"theme": "dark", "lang": "en"})

# Search governed memory with hybrid retrieval
results = store.search(("user",), query="user interface preferences", limit=5)
for item in results:
    print(item.key, item.value, item.score)

2. LangGraph Checkpointer (thread state via OCF session handoff)

from langgraph.graph import StateGraph
from artesian_langchain import ArtesianClient, ArtesianSaver

client = ArtesianClient(backend="sqlite-vec")
checkpointer = ArtesianSaver(client=client, agent_id_prefix="myapp")

# Build your LangGraph graph
graph = StateGraph(...)
compiled = graph.compile(checkpointer=checkpointer)

# Run with a thread id — checkpoint is stored via artesian session checkpoint
# and can be resumed by ANY agent that uses Artesian (Claude Code, Codex, etc.)
result = compiled.invoke(
    {"messages": [{"role": "user", "content": "Hello"}]},
    config={"configurable": {"thread_id": "user-session-42"}},
)

3. LangChain Chat History (per-session governed history)

from langchain_core.messages import HumanMessage, AIMessage
from artesian_langchain import ArtesianClient, ArtesianChatMessageHistory

client = ArtesianClient()
history = ArtesianChatMessageHistory(
    session_id="user-session-42",
    client=client,
    namespace="chat-history",
    scope="session",
)

# Add messages — each is stored as a governed Artesian memory record
history.add_messages([
    HumanMessage(content="What's the capital of France?"),
    AIMessage(content="Paris."),
])

# Retrieve — messages come back through Artesian hybrid retrieval
for msg in history.messages:
    print(msg.type, msg.content)

Configuration

ArtesianClient accepts:

Parameter Type Default Description
binary str "artesian" Path or name of the artesian binary
config str | None None Path to artesian.toml config file
root str | None None Path to .artesian root directory
backend str | None None Backend override: "files", "sqlite-vec", "qdrant"
cwd str | None None Working directory for subprocesses
env dict[str, str] {} Extra environment variables
timeout float 30.0 Subprocess timeout in seconds

Transport design

All adapters shell out to the artesian CLI via subprocess. This is intentional:

  • Works wherever artesian is installed — no Python SDK to maintain in lock-step
  • All governance goes through Artesian — qualify-gate, OCF format, provenance, token accounting
  • No direct database access — the Python layer never touches Qdrant, SQLite, or file stores
  • Configurable binary path — works with a system install, a virtual env, or a container path

License

Apache-2.0 — see LICENSE.

About

LangChain + LangGraph memory adapter for Artesian — recall, commit, and session handoff through governed agent memory

Topics

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages