tidbits-memory

A memory/tidbits voting framework for AI agents. Agents can record learnings (facts, methods, gotchas) and vote on them to surface the most useful tidbits.

Installation

uv pip install -e ".[dev]"

Quick start

from tidbits_memory.adapters.memory import InMemoryAdapter
from tidbits_memory.store import MemoryStore

store = MemoryStore(InMemoryAdapter())

# Create a voter id for this session
voter_id = store.create_voter_id()

# Create a memory
mem = store.create_memory("Python dicts preserve insertion order since 3.7", voter_id=voter_id)

# Get memories (random order, no vote counts) — ideal for agent consumption
result = store.get_memories(voter_id=voter_id)
print(result["memories"])

# Upvote a useful memory
store.upvote_memory(mem.id, voter_id="another-session-id")

# List memories sorted by votes (most upvoted first)
for m in store.list_memories():
    print(f"[{m.votes}] {m.content}")

# Downvote an erroneous memory
store.downvote_memory(mem.id, voter_id="yet-another-session")

# Unvote (remove a prior vote)
store.unvote_memory(mem.id, "another-session-id")

# Remove a memory
store.remove_memory(mem.id)

Persistent storage (JSON file)

from tidbits_memory.adapters.json_file import JsonFileAdapter
from tidbits_memory.store import MemoryStore

store = MemoryStore(JsonFileAdapter("memories.json"))
store.create_memory("Use `uv` for fast Python packaging")

Voter ID generation

When an agent doesn't have a session/conversation ID, use create_voter_id:

voter_id = store.create_voter_id()
# Use this voter_id for all votes in this session

If no voter_id is provided when calling get_memories, one is automatically generated and returned in the response.

MCP Tool Wrappers

from mcp.server import FastMCP
from tidbits_memory.adapters.memory import InMemoryAdapter
from tidbits_memory.store import MemoryStore
from tidbits_memory.tools import register_tools

store = MemoryStore(InMemoryAdapter())
mcp = FastMCP("tidbits")
register_tools(mcp, store)

# Registered tool names:
# create_memory, upvote_memory, downvote_memory, unvote_memory,
# list_memory, get_memories, remove_memory, create_voter_id

Running tests

uv run pytest