Python SDK

Native Python bindings via PyO3. Import as import pensyve.

pip install pensyve

The Python SDK is a compiled Rust extension. It runs locally with no server required.

`Pensyve`

Main entry point for the memory runtime.

`Pensyve(path?, namespace?)`

Create or open a Pensyve instance.

Parameter	Type	Default	Description
`path`	`str \| None`	`~/.pensyve/default`	Directory for storage files
`namespace`	`str \| None`	`"default"`	Namespace name

from pensyve import Pensyve

p = Pensyve()
p = Pensyve(path="/tmp/mydata", namespace="project-x")

`entity(name, kind?)`

Get or create an entity.

Parameter	Type	Default	Description
`name`	`str`	required	Entity name
`kind`	`str`	`"user"`	One of `"agent"`, `"user"`, `"team"`, `"tool"`

Returns: Entity

user = p.entity("alice")
agent = p.entity("my-agent", kind="agent")

`episode(*participants)`

Create an episode context manager. Episodes record messages and produce memories on exit.

Parameter	Type	Default	Description
`*participants`	`Entity`	required	Entities participating in this episode

Returns: Episode (context manager)

user = p.entity("alice")
agent = p.entity("my-agent", kind="agent")

with p.episode(user, agent) as ep:
    ep.message("user", "What's the status of project X?")
    ep.message("assistant", "Project X is on track for Q2 launch.")
    ep.outcome("success")

`recall(query, entity?, limit?, types?)`

Search memories matching a query. Fuses vector, BM25, graph, recency, and other signals.

Parameter	Type	Default	Description
`query`	`str`	required	Search query
`entity`	`Entity \| None`	`None`	Filter to a specific entity
`limit`	`int`	`5`	Max results
`types`	`list[str] \| None`	`None`	Filter by memory type: `"episodic"`, `"semantic"`, `"procedural"`

Returns: list[Memory]

memories = p.recall("project X deadline")
memories = p.recall("deployment steps", entity=agent, limit=10, types=["procedural"])

`remember(entity, fact, confidence?)`

Store an explicit semantic memory.

Parameter	Type	Default	Description
`entity`	`Entity`	required	Entity this fact is about
`fact`	`str`	required	The fact to store
`confidence`	`float`	`0.8`	Confidence in `[0, 1]`

Returns: Memory

m = p.remember(user, "Alice prefers dark mode")
m = p.remember(user, "Alice is on the platform team", confidence=0.95)

`forget(entity, hard_delete?)`

Archive or permanently delete all memories about an entity.

Parameter	Type	Default	Description
`entity`	`Entity`	required	Target entity
`hard_delete`	`bool`	`False`	Permanently delete instead of archiving

Returns: dict[str, int] with key forgotten_count

result = p.forget(user)
result = p.forget(user, hard_delete=True)

`consolidate()`

Run background consolidation: promotes repeated episodic memories to semantic, applies FSRS decay, and archives memories below threshold.

Returns: dict[str, int] with keys promoted, decayed, archived

stats = p.consolidate()
# {'promoted': 3, 'decayed': 12, 'archived': 1}

`Entity`

Represents an entity (agent, user, team, or tool). Created via Pensyve.entity().

Property	Type	Description
`id`	`str`	UUID
`name`	`str`	Entity name
`kind`	`str`	`"agent"`, `"user"`, `"team"`, or `"tool"`

`Episode`

Context manager that records messages and creates memories on exit. Created via Pensyve.episode().

`message(role, content)`

Record a message in this episode.

Parameter	Type	Default	Description
`role`	`str`	required	Speaker role (e.g. `"user"`, `"assistant"`)
`content`	`str`	required	Message content

Returns: None

`outcome(result)`

Set the episode outcome. Affects procedural memory reliability tracking.

Parameter	Type	Default	Description
`result`	`str`	required	One of `"success"`, `"failure"`, `"partial"`

Returns: None

`Memory`

A retrieved memory record. Returned by recall() and remember().

Property	Type	Description
`id`	`str`	UUID
`content`	`str`	Memory text
`memory_type`	`str`	`"episodic"`, `"semantic"`, or `"procedural"`
`confidence`	`float`	Confidence in `[0, 1]`
`stability`	`float`	FSRS stability in `[0, 1]`
`score`	`float`	Retrieval score from the recall engine

On this page