ppl-memory
ppl (withppl.com) as a memory backend for agent frameworks.
ppl is a personal CRM. This package makes it the memory layer for your agents: agents remember facts about people and recall them in later sessions, without keeping anything in their own context. The memory lives in the user's ppl account, so it survives across sessions, agents, and frameworks.
Supported frameworks (one package, framework extras):
| Framework | Extra | Class |
|---|---|---|
| LangGraph | ppl-memory[langchain] |
PplStore (BaseStore) |
| CrewAI | ppl-memory[crewai] |
PplCrewAIStorage (StorageBackend) |
| AutoGen 0.4 | ppl-memory[autogen] |
PplMemory (Memory) |
| Mem0 | ppl-memory[mem0] |
PplMem0 (MemoryBase) |
| LlamaIndex | ppl-memory[llamaindex] |
PplMemoryBlock (BaseMemoryBlock) |
| OpenAI Agents SDK | ppl-memory[openai-agents] |
PplSession (Session) |
| Semantic Kernel | ppl-memory[semantic-kernel] |
PplMemoryPlugin (kernel functions) |
| Vercel AI SDK | npm install ppl-memory |
createPplTools() (AI SDK tools, in ppl-memory-js/) |
Setup
- Create an API token at withppl.com/settings/agents.
- Export it:
export PPL_API_TOKEN="your-token"
Optionally set a default contact for memories: export PPL_DEFAULT_CONTACT="Jane Smith" (name or contact id).
- Install the extra for your framework:
pip install ppl-memory[langchain] # or [crewai], [autogen], [mem0],
# [llamaindex], [openai-agents], or [semantic-kernel]
TypeScript users (Vercel AI SDK): npm install ppl-memory (same name, same
repo, in ppl-memory-js/; see that directory's README).
LangGraph
PplStore implements LangGraph's BaseStore. Memories are namespaced per
contact: namespace ("memories", <contact id or name>). put stores a fact
as a note on that contact's timeline; get retrieves it back; search
runs ppl's ranked retrieval over everything ppl knows.
from langgraph.checkpoint.memory import MemorySaver
from langgraph.graph import StateGraph
from ppl_memory.langchain import PplStore
store = PplStore(default_contact="Jane Smith")
# remember
store.put(("memories", "Jane Smith"), "coffee", {"fact": "Jane drinks oat milk lattes."})
# recall in a later session
item = store.get(("memories", "Jane Smith"), "coffee")
print(item.value["fact"])
# natural-language search across the whole CRM
for hit in store.search(("memories",), query="What does Jane like to drink?"):
print(hit.value["fact"], hit.score)
# use it in a graph
graph = StateGraph(...).compile(checkpointer=MemorySaver(), store=store)
CrewAI
PplCrewAIStorage implements CrewAI's unified-memory StorageBackend
protocol. Use it as the storage for the unified Memory:
from crewai import Agent, Crew, Task, Process
from crewai.memory import Memory
from ppl_memory.crewai import PplCrewAIStorage
memory = Memory(storage=PplCrewAIStorage(default_contact="Jane Smith"))
crew = Crew(
agents=[...],
tasks=[...],
process=Process.sequential,
memory=memory,
)
memory.remember("The customer prefers email over phone", scope="/clients/acme")
memory.recall("how should we contact acme?", scope="/clients")
save() writes each record as a note on the contact's timeline (contact from
record metadata, a /contacts/<name> scope, or the default contact).
search() scores records with cosine similarity against a local embedding
cache (~/.ppl-memory/crewai_embeddings.json; derived vectors only, the
memory content lives in ppl). delete() removes only notes this backend
created; your other CRM data is untouched.
AutoGen 0.4
PplMemory implements the autogen_core Memory protocol.
import asyncio
from autogen_core.memory import MemoryContent
from autogen_core.model_context import BufferedChatCompletionContext
from ppl_memory.autogen import PplMemory
async def main():
memory = PplMemory(default_contact="Jane Smith")
await memory.add(MemoryContent(
content="Jane's birthday is Friday.",
mime_type="text/plain",
metadata={"contact": "Jane Smith"},
))
result = await memory.query("When is Jane's birthday?")
print(result.results[0].content)
# inject relevant memories into the model context
context = BufferedChatCompletionContext(buffer_size=10)
await memory.update_context(context)
asyncio.run(main())
update_context() takes the latest user message, queries ppl for relevant
memories, and adds them as a system message. clear() is a deliberate no-op:
ppl holds real CRM history and must not be wiped by a memory reset.
Mem0
PplMem0 subclasses mem0's MemoryBase, so it works anywhere a Mem0 memory
store is expected, with Mem0-style add/search result shapes.
from ppl_memory.mem0 import PplMem0
memory = PplMem0(default_contact="Jane Smith")
# add: messages as a string or [{"role": ..., "content": ...}] list
result = memory.add(
[{"role": "user", "content": "Jane's birthday is Friday."}],
user_id="Jane Smith",
)
print(result["results"][0]["id"])
# search
hits = memory.search("When is Jane's birthday?", user_id="Jane Smith")
print(hits["results"][0]["memory"])
# get / get_all / update / delete / history follow the MemoryBase interface
mem = memory.get(result["results"][0]["id"])
memory.update(mem["id"], "Jane's birthday is Saturday, not Friday.")
memory.delete(mem["id"])
user_id selects the ppl contact (id or name); default_contact is the
fallback. delete_all() and reset() are deliberate no-ops: ppl is the
system of record and is never wiped by an adapter.
LlamaIndex
PplMemoryBlock is a LlamaIndex BaseMemoryBlock[str]. Drop it into a
Memory alongside LlamaIndex's other blocks:
from llama_index.core.memory import Memory
from ppl_memory.llama_index import PplMemoryBlock
memory = Memory(
memory_blocks=[PplMemoryBlock(default_contact="Jane Smith")],
token_limit=30000,
)
agent = ReActAgent.from_tools(tools, llm=llm, memory=memory)
aput writes messages as a note on the contact's timeline (marked
[ppl-llamaindex]); aget runs ppl's ranked retrieval over the latest user
message and returns the hits as text for the memory template. The contact
comes from default_contact (or PPL_DEFAULT_CONTACT), or per-message
additional_kwargs contact/contact_id keys.
OpenAI Agents SDK
PplSession implements the agents Session protocol, so it drops straight
into Runner.run:
from agents import Agent, Runner
from ppl_memory.openai_agents import PplSession
agent = Agent(name="assistant", instructions="You are helpful.")
session = PplSession(session_id="chat-123", default_contact="Jane Smith")
result = await Runner.run(agent, "Remember that Jane likes tea.", session=session)
# a later run with the same session_id replays the conversation
add_items stores the conversation as notes on the contact's timeline (marked
per session); get_items replays them in order; pop_item removes the most
recent item; clear_session is a deliberate no-op, since ppl holds real CRM
history and must not be wiped by a session reset.
Semantic Kernel
PplMemoryPlugin exposes ppl as kernel functions (ppl-remember,
ppl-recall, ppl-briefing):
from semantic_kernel import Kernel
from ppl_memory.semantic_kernel import PplMemoryPlugin
kernel = Kernel()
kernel.add_plugin(PplMemoryPlugin(default_contact="Jane Smith"), plugin_name="ppl")
result = await kernel.invoke(
kernel.get_function("ppl", "recall"),
query="What does Jane like to drink?",
)
print(result)
remember(contact, fact) stores a fact on the contact's timeline (contact
may be an id or a name); recall(query) returns ranked hits as text;
briefing() returns the morning briefing.
Vercel AI SDK (TypeScript)
The TypeScript side lives in ppl-memory-js/ in this repo and is published
as ppl-memory on npm (same package name, same version). It wraps the same
ppl REST API as AI SDK tools:
import { generateText } from 'ai';
import { createPplTools } from 'ppl-memory';
const { text } = await generateText({
model: myModel,
tools: createPplTools(), // reads PPL_API_TOKEN
prompt: 'What does Jane like to drink?',
});
Tools: pplRemember, pplRecall, pplBriefing, pplFindContact. See
ppl-memory-js/README.md.
Raw client
from ppl_memory import PplClient
client = PplClient() # reads PPL_API_TOKEN
client.remember(contact_id=123, fact="Jane prefers email over phone.")
client.ask("How should I reach Jane?") # ranked retrieval
client.search("birthday") # semantic search
client.get_briefing() # morning briefing
Notes
- Memories are stored as notes on contact timelines in ppl. They are visible in the ppl web app, which is the point: the user's memory is inspectable.
- The human never handles the token for framework setup beyond the one-time export; the agent drives the rest via withppl.com/agents.
- Not affiliated with LangChain, CrewAI, Microsoft, OpenAI, Meta (LlamaIndex), or Vercel. ppl is a standalone personal CRM by Cumulative Systems.
License
MIT
Metadata
Release files for ppl-memory 0.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ppl_memory-0.3.0.tar.gz | 42.1 kB | With provenance | Details for ppl_memory-0.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ppl_memory-0.3.0-py3-none-any.whl | Python 3 | none | any | Details for ppl_memory-0.3.0-py3-none-any.whl |
Total release size: 70.2 kB
Release files / ppl_memory-0.3.0.tar.gz
| Download URL | ppl_memory-0.3.0.tar.gz |
|---|---|
| Size | 42.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b323e14ce40d4ec758e26a8e45379647e2c93ea77d2b3608da2f441efb828505
|
|
BLAKE2b-256 checksum How to use checksums |
d2ccdaa2f205baaf62f4fad247edc4bda84a76021e8692de2d916d075d558def
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 6, 2026.
Transparency logRelease files / ppl_memory-0.3.0-py3-none-any.whl
| Download URL | ppl_memory-0.3.0-py3-none-any.whl |
|---|---|
| Size | 28.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9e6db6b4f5101dbf25b6fed6941b145e36407934da720dcfe0937e305eb8ac47
|
|
BLAKE2b-256 checksum How to use checksums |
2176d8afd5aab9a6408175800b402a0e0427ec378eeaf4cf338e84539484bc80
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 6, 2026.
Transparency logSecurity for ppl-memory 0.3.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.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for ppl_memory-0.3.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 6, 2026.
Transparency logA 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.