Skip to main content

Membase for Haystack

membase-haystack gives Haystack agents and pipelines your Membase account as their long-term memory:

Piece Haystack type What it does
MembaseMemoryStore memory store Owns the Membase client: search_memories, add_memories, profile.
MembaseMemoryRetriever @component Pipeline read path: memories as system ChatMessages. Time-boxed, fails open.
membase_tools() Tools membase_search, membase_save and membase_profile for an Agent.

Every passage names the Memory it came from, e.g. [Project decisions] We chose Postgres for the ledger., so the model can cite it. There is no delete tool.

Install

pip install membase-haystack
export MEMBASE_API_KEY="mbk_…"     # Connect › Developer keys in the Membase app

A Read key can search and, with Profile ticked, read the profile. Saving needs a Read & write key whose writes have one place to go: a key that reaches a single Memory saves there.

Use with an Agent

from haystack.components.agents import Agent
from haystack.components.generators.chat import OpenAIChatGenerator
from haystack.dataclasses import ChatMessage

from membase_haystack import MembaseMemoryStore, membase_tools

store = MembaseMemoryStore()  # MEMBASE_API_KEY from the environment

agent = Agent(
    chat_generator=OpenAIChatGenerator(),
    tools=membase_tools(store),
    system_prompt=(
        "You are a helpful assistant with long-term memory. Search Membase before answering anything that "
        "may depend on what the user told you before, and cite the Memory in brackets. Save to Membase only "
        "when the user asks you to remember something."
    ),
)

result = agent.run(messages=[ChatMessage.from_user("Which database did we pick for the ledger?")])
print(result["last_message"].text)
Tool What it does
membase_search(query, limit?) Searches every Memory the key reaches; each passage is cited as [Memory name] …, and a Memory that could not answer is said so.
membase_save(content) Saves a note in the user's words, only when the user asks.
membase_profile() Reads the user's profile facts, newest first. Needs Profile access on the key.

membase_tools(store, tools=("search", "profile")) leaves saving out, e.g. for a Read key.

Use in a pipeline

MembaseMemoryRetriever puts the relevant memories in front of the model on every run:

from haystack import Pipeline
from haystack.components.builders import ChatPromptBuilder
from haystack.components.generators.chat import OpenAIChatGenerator
from haystack.dataclasses import ChatMessage

from membase_haystack import MembaseMemoryRetriever, MembaseMemoryStore

template = [
    ChatMessage.from_system(
        "Memory from Membase (cite the Memory in brackets):\n{% for m in memories %}{{ m.text }}\n{% endfor %}"
    ),
    ChatMessage.from_user("{{ question }}"),
]

pipeline = Pipeline()
pipeline.add_component("memory", MembaseMemoryRetriever(memory_store=MembaseMemoryStore(), top_k=5))
pipeline.add_component("prompt", ChatPromptBuilder(template=template, required_variables=["question"]))
pipeline.add_component("llm", OpenAIChatGenerator())
pipeline.connect("memory.memories", "prompt.memories")
pipeline.connect("prompt.prompt", "llm.messages")

question = "Which database did we pick for the ledger?"
result = pipeline.run({"memory": {"query": question}, "prompt": {"question": question}})
print(result["llm"]["replies"][0].text)

The retriever's search gets 8 seconds by default (recall_timeout), because the first search after a quiet spell can take up to a minute while the memory wakes. When it runs out, the retriever returns no memories and the pipeline goes on; the search keeps running, so the memory is awake for the next run.

store.add_memories(messages=...) saves the user messages' text as one note, so you can keep what the user said after a run. It keeps the user's own words only.

One key is one person

A Membase key belongs to one person's account, so one MembaseMemoryStore serves one person. In a multi-user app, build the store per user from that user's own key:

from haystack.utils import Secret

store = MembaseMemoryStore(api_key=Secret.from_token(key_for(user_id)))

The store and the retriever serialize with the pipeline. The key is written as a Secret, so an environment-variable key stays a reference and a token key refuses to serialize.

Haystack 3 loads only the components of modules on its deserialization allowlist, so allow this package's module before loading a saved pipeline (Haystack 2 needs no step):

from haystack.core.serialization import allow_deserialization_module

allow_deserialization_module("membase_haystack.memory")
pipeline = Pipeline.loads(saved)

Or set HAYSTACK_DESERIALIZATION_ALLOWLIST=membase_haystack.memory in the environment.

Local memory

pip install 'membase-haystack[local]'
store = MembaseMemoryStore(local="~/.membase")

Requirements

Python 3.10+, haystack-ai and unibaseio-membase 0.4.0 or newer.

MIT licensed.

Metadata

Release files for membase-haystack 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for membase-haystack 0.1.0
File Size Uploaded Provenance Actions
membase_haystack-0.1.0.tar.gz 11.3 kB Without provenance Details for membase_haystack-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for membase-haystack 0.1.0
File Interpreter ABI Platform Actions
membase_haystack-0.1.0-py3-none-any.whl Python 3 none any Details for membase_haystack-0.1.0-py3-none-any.whl

Total release size: 21.2 kB

Release files / membase_haystack-0.1.0.tar.gz

Download URL membase_haystack-0.1.0.tar.gz
Size 11.3 kB
Tags Source
SHA-256 checksum
How to use checksums
bba876aceb4fe33256928492b4b6d0ba16505c29fcedbff2b959e4000e7f8413
BLAKE2b-256 checksum
How to use checksums
ae5c6737325cc1d2bbfbb7562fe0d46a8959ce95d92957ba190854fdc0e0ad7a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.12

Release files / membase_haystack-0.1.0-py3-none-any.whl

Download URL membase_haystack-0.1.0-py3-none-any.whl
Size 9.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b1800ea01d983db120b2825fe14ddf4ce967450053aebe5a025047e2b85770fd
BLAKE2b-256 checksum
How to use checksums
5e662f0baa4385c8ba872899ee51a25b92aa108e7a18b27d9eaa9f0b80a4fef3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.12

Security for membase-haystack 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page