stigmem-plugin-letta-adapter

Bridges Stigmem with Letta, the open-source memory and persistence layer for LLM agents.

This package is experimental and opt-in. Installing it makes the letta-adapter plugin discoverable through the stigmem.plugins entry-point group; host applications still choose when to call the adapter.

Federation model

The adapter writes Stigmem facts into a Letta agent's archival memory as [stigmem]-tagged passages and reads them back as Stigmem-compatible records. Native Letta passages can be returned as letta:archival_memory fallback records or filtered with stigmem_only=True.

Design

• Facts are serialized as structured text with a [stigmem] prefix.
• pull_from_letta() parses the prefix back to fact fields.
• batch_push_to_letta() pushes multiple facts to the same target agent.
• letta is a lazy optional import; discovery and tests do not require it.

Files

Installation

python -m pip install 'stigmem-plugin-letta-adapter>=0.1.0,<2.0.0'

Install Letta only in deployments that run the live bridge:

python -m pip install 'stigmem-plugin-letta-adapter[letta]>=0.1.0,<2.0.0'

Requirements

• Python >= 3.11
• stigmem-py: pip install stigmem-py (or from workspace)
• letta: optional runtime extra for live Letta calls; unit tests and plugin discovery do not require it.
• A running Letta server for live use: letta server (default: http://localhost:8283)

Environment variables

LETTA_URL=http://localhost:8283  # default
LETTA_TOKEN=your-token           # optional for local server

Usage

Push a fact into a Letta agent's memory

from stigmem_plugin_letta import StigmemLettaAdapter

bridge = StigmemLettaAdapter.from_env()

fact = {
    "entity": "project:loom",
    "relation": "roadmap:phase",
    "value": {"type": "string", "v": "phase-6"},
    "source": "agent:distsyseng",
    "scope": "company",
    "confidence": 1.0,
}

bridge.push_to_letta(fact, agent_id="your-letta-agent-uuid")

Seed an agent at startup

from stigmem import StigmemClient

client = StigmemClient(url="http://localhost:8765")
page = client.query(entity="project:loom", scope="company")

bridge.batch_push_to_letta(
    [f.model_dump() for f in page.facts],
    agent_id="your-letta-agent-uuid",
)

Pull agent memory as Stigmem records

records = bridge.pull_from_letta(
    agent_id="your-letta-agent-uuid",
    scope="company",
)

stigmem_records = bridge.pull_from_letta(
    agent_id="your-letta-agent-uuid",
    scope="company",
    stigmem_only=True,
)

Enable

The adapter has no node-global behavior gate at v0.1.0. Enable it in the host application by installing the package and importing stigmem_plugin_letta.StigmemLettaAdapter.

python -m pip install 'stigmem-plugin-letta-adapter>=0.1.0,<2.0.0'
python -m pip install 'stigmem-plugin-letta-adapter[letta]>=0.1.0,<2.0.0'  # live Letta bridge
stigmem plugins list

Disable

Remove the adapter from the host application path and restart the process that loads plugins. If it was installed only for this integration, uninstall it:

python -m pip uninstall stigmem-plugin-letta-adapter

Test

cd experimental/letta-adapter
python -m pytest tests/ -v

No live Stigmem node or Letta server required; the letta module is mocked in the test suite.

Uninstall

python -m pip uninstall stigmem-plugin-letta-adapter

Invariants

• The adapter only appends to archival memory; it never modifies core memory blocks or deletes passages.
• Letta is a secondary enrichment layer. Failures in push_to_letta or pull_from_letta do not affect Stigmem availability.
• Callers own retry, circuit-breaker, and prompt/write policy.