store

store

Persistent stores for automatically extracted long-term memory facts.

A fact is a short, durable statement worth remembering about the user (e.g. "Prefers concise answers"). Facts are produced by the memory service's background extractor and persisted here so they survive across sessions. The store is intentionally small and self-contained: it dedupes, caps the total number of facts, and is safe to call from multiple threads.

Classes

Fact dataclass

Fact(text: str, source: str = '', created_at: float = 0.0)

A single durable memory entry.

FactStore

Bases: ABC

Abstract persistent store for extracted memory facts.

Functions

add abstractmethod

add(text: str, source: str = '') -> bool

Store text as a fact. Returns True if a new fact was stored.

Source code in src/openjarvis/memory/store.py

@abstractmethod
def add(self, text: str, source: str = "") -> bool:
    """Store *text* as a fact. Returns True if a new fact was stored."""

add_many

add_many(texts: Iterable[str], source: str = '') -> int

Store several facts, returning the count of newly stored ones.

Source code in src/openjarvis/memory/store.py

def add_many(self, texts: Iterable[str], source: str = "") -> int:
    """Store several facts, returning the count of newly stored ones."""
    added = 0
    for text in texts:
        if self.add(text, source=source):
            added += 1
    return added

list abstractmethod

list() -> List[Fact]

Return all stored facts, oldest first.

Source code in src/openjarvis/memory/store.py

@abstractmethod
def list(self) -> List[Fact]:
    """Return all stored facts, oldest first."""

clear abstractmethod

clear() -> int

Remove all stored facts, returning the number removed.

Source code in src/openjarvis/memory/store.py

@abstractmethod
def clear(self) -> int:
    """Remove all stored facts, returning the number removed."""

count abstractmethod

count() -> int

Return the number of stored facts.

Source code in src/openjarvis/memory/store.py

@abstractmethod
def count(self) -> int:
    """Return the number of stored facts."""

LocalFactStore

LocalFactStore(path: str | Path = '~/.openjarvis/memory_facts.jsonl', *, max_facts: int = 1000)

Bases: FactStore

Append-only JSONL fact store on the local filesystem.

Facts are kept human-readable (one JSON object per line) so they can be inspected or edited by hand. Writes are atomic (temp file + rename) and guarded by a lock, so concurrent add calls from the extraction worker and list/clear from the CLI never corrupt the file.

Source code in src/openjarvis/memory/store.py

def __init__(
    self,
    path: str | Path = "~/.openjarvis/memory_facts.jsonl",
    *,
    max_facts: int = 1000,
) -> None:
    self._path = Path(path).expanduser()
    self._max_facts = max(0, int(max_facts))
    self._lock = threading.Lock()
    self._facts: List[Fact] = self._load()

Attributes

path property

path: Path

Filesystem location of the JSONL store.

Functions

create_fact_store

create_fact_store(backend: str = 'local', *, path: str | Path = '~/.openjarvis/memory_facts.jsonl', max_facts: int = 1000) -> FactStore

Construct a fact store for the configured backend.

Only the "local" (on-disk JSONL) backend is supported today; the factory exists so additional backends can be added without changing the service or CLI wiring.

Source code in src/openjarvis/memory/store.py

def create_fact_store(
    backend: str = "local",
    *,
    path: str | Path = "~/.openjarvis/memory_facts.jsonl",
    max_facts: int = 1000,
) -> FactStore:
    """Construct a fact store for the configured *backend*.

    Only the ``"local"`` (on-disk JSONL) backend is supported today; the
    factory exists so additional backends can be added without changing the
    service or CLI wiring.
    """
    key = (backend or "local").strip().lower()
    if key == "local":
        return LocalFactStore(path, max_facts=max_facts)
    raise ValueError(f"Unknown memory backend '{backend}'. Supported backends: local")