oc_chat.tools.memory Namespace Reference

Functions
str	_store_dir ()
	_get_collection ()
dict	remember (str text, dict|None metadata=None)
dict	recall (str query, int n_results=5)

Variables
str	_COLLECTION_NAME = "oc_chat_memory"
	_client = None
	_collection = None
dict	TOOLS
list	SCHEMAS

Detailed Description

Persistent memory via ChromaDB vector store.

Purpose
-------
Provides :func:`remember` and :func:`recall` for long-term semantic
memory across REPL sessions. Backed by a local ChromaDB persistent
client at ``./memory_store/`` with cosine-similarity search.

Falls back to the structured ``missing_dependency`` shape that the
dependency healer can intercept when ``chromadb`` is not installed.

Responsibilities
----------------
- :func:`_get_collection` — lazily build (or reload) the persistent
  collection on first access.
- :func:`remember` — embed and store a text chunk with optional
  metadata; returns the assigned id.
- :func:`recall` — semantic-similarity query returning the top-k
  matches with their metadata and distances.

Requires: ``pip install chromadb``

Diagnostics
-----------
Domain: OC_CHAT.TOOLS
Levels:
    L2 — lifecycle events
    L3 — semantic details
    L4 — deep tracing

Contracts
---------
- The collection is process-singleton — repeat calls reuse the same
  client/collection handles.
- Missing ``chromadb`` returns ``{"missing_dependency": "chromadb",
  ...}`` rather than raising, so the healer can offer to install.
- The on-disk store at ``memory_store/`` is opaque to callers; only
  the public ``remember`` / ``recall`` API is supported.

Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
- oc_chat.tools.filesystem (lazy; _sandbox_root - places the memory store under the effective sandbox root)
- chromadb (lazy; the persistent vector store client and its cosine-similarity collection, optional)

See Also
--------
oc_chat/docs/conventions/CONTRACTS.md §3 Tool registry contract; §4 Tool return-
value conventions.

Function Documentation

_get_collection()

oc_chat.tools.memory._get_collection ( )

protected

Return (or lazily create) the ChromaDB collection.

Definition at line 76 of file memory.py.

Here is the call graph for this function:

Here is the caller graph for this function:

_store_dir()

str oc_chat.tools.memory._store_dir ( )

protected

Resolve the memory store dir under the effective sandbox root.

Resolved at first use (not import time) so a session sandbox override set
after import is honoured — keeping the long-term memory store aligned with
the read/write sandbox (M8 F77; M8.0 WU-1) instead of the import-time
process cwd.

Definition at line 60 of file memory.py.

Here is the caller graph for this function:

recall()

dict oc_chat.tools.memory.recall	(	str	query,
		int	n_results = 5 )

Retrieve relevant memories using semantic similarity search.

Definition at line 110 of file memory.py.

Here is the call graph for this function:

remember()

dict oc_chat.tools.memory.remember	(	str	text,
		dict | None	metadata = None )

Store a piece of information in long-term persistent memory.

Definition at line 97 of file memory.py.

Here is the call graph for this function:

Variable Documentation

_client

oc_chat.tools.memory._client = None

protected

Definition at line 72 of file memory.py.

_collection

oc_chat.tools.memory._collection = None

protected

Definition at line 73 of file memory.py.

_COLLECTION_NAME

str oc_chat.tools.memory._COLLECTION_NAME = "oc_chat_memory"

protected

Definition at line 71 of file memory.py.

SCHEMAS

list oc_chat.tools.memory.SCHEMAS

Definition at line 140 of file memory.py.

TOOLS

dict oc_chat.tools.memory.TOOLS

Initial value:

=  {
    "remember": remember,
    "recall":   recall,
}

Definition at line 135 of file memory.py.