Durable skills and explicit forgetting

Store selected procedural documents or programs without executing them.

Use the existing ToolArtifact / BaseToolLibrary seam for procedural documents and executable source. SqliteToolLibrary(path, namespace=...) is an owned local SQLite implementation: close it or use a context manager. The caller selects a trusted private database path. Namespace labels isolate records, not operating system users who can read that same file.

add_or_update(..., expected_version=...) atomically publishes a new immutable revision and detects stale writers. catalog returns descriptions without bodies; get and get_version load complete selected bodies. Selection, validation, trust, code execution and retention policy remain the agent author’s decisions. The library never executes a program and is not a permission bypass. Store JSON metadata such as source, checker digest and ArtifactRef declarations; never live clients, credentials or Python callables. Rejecting invalid data does not repair it.

The Hermes and Voyager courses use the same store for different payloads. Neither silently shortens a selected skill to fit a prompt: request budgets must fit it or fail explicitly. Existing in-memory implementations remain usable through the same base seam; this is not a new root-level export.

MemdirMemory.delete(record_id) forgets a local hashed record and its index entry. Missing identities return false; malformed or symlink-backed resources are rejected. It is not secure erasure, historical trajectory deletion, a multi-file transaction, or a concurrent-writer protocol. Reopening a memory root does not initialize it.

Hermes course · Voyager course

The source links below pin immutable implementation commits. Install a wheel built from the matching repository source; this is not a separate PyPI release.

ToolArtifact

from qitos.kit.tool.library.base import ToolArtifact

Source @ 19f6258

Usage and executable example

Usage fragment: continues with objects from the linked complete tutorial; not a standalone program.

artifact = ToolArtifact(name="audit", description="Check evidence", source="Read, calculate, verify.")

Field	Type	Default
name	str	required
description	str	required
source	str	required
summary	Optional[str]	None
tags	List[str]	field(default_factory=list)
version	int	1
created_at	str	field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
updated_at	str	field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
metadata	Dict[str, Any]	field(default_factory=dict)
active	bool	True

BaseToolLibrary

from qitos.kit.tool.library.base import BaseToolLibrary

Source @ 19f6258

Usage and executable example

Usage fragment: continues with objects from the linked complete tutorial; not a standalone program.

# Implement this existing contract to replace the local SQLite mechanism.

BaseToolLibrary.get

get(name: str) -> Optional[ToolArtifact]

Parameter	Type	Default
name	str	required

Source

BaseToolLibrary.search

search(query: str, top_k: int=5) -> List[ToolArtifact]

Parameter	Type	Default
query	str	required
top_k	int	5

Source

BaseToolLibrary.add_or_update

add_or_update(artifact: ToolArtifact) -> ToolArtifact

Parameter	Type	Default
artifact	ToolArtifact	required

Source

SqliteToolLibrary

from qitos.kit.tool.library.sqlite_store import SqliteToolLibrary

Source @ 19f6258

Usage and executable example

Usage fragment: continues with objects from the linked complete tutorial; not a standalone program.

with SqliteToolLibrary(private_path, namespace="research") as library:
    stored = library.add_or_update(artifact)
    print(library.catalog("audit"))
    assert library.get_version(stored.name, stored.version).source == artifact.source

Atomic revisions scoped to an explicitly selected namespace.

A catalog exposes descriptions, never executable source. ``get`` loads the
complete selected artifact; no implicit truncation or execution takes place.
The caller owns the connection and must close it (or use a context manager).
SQLite is a trusted local resource, not an authorization boundary against a
user who can directly open the same database file.

SqliteToolLibrary(path: str | Path, *, namespace: str) -> Any (see behavior contract)

Parameter	Type	Default
path	str | Path	required
namespace	str	required

SqliteToolLibrary.add_or_update

add_or_update(artifact: ToolArtifact, *, expected_version: Optional[int]=None) -> ToolArtifact

Parameter	Type	Default
artifact	ToolArtifact	required
expected_version	Optional[int]	None

Source

SqliteToolLibrary.get

get(name: str) -> Optional[ToolArtifact]

Parameter	Type	Default
name	str	required

Source

SqliteToolLibrary.get_version

get_version(name: str, version: int) -> Optional[ToolArtifact]

Parameter	Type	Default
name	str	required
version	int	required

Source

SqliteToolLibrary.catalog

catalog(query: str='', *, limit: int=20) -> list[dict[str, Any]]

Parameter	Type	Default
query	str	''
limit	int	20

Return selectable identities/descriptions without source or metadata.

This is a projection, not a privacy sanitizer or bounded-I/O claim.

Source

SqliteToolLibrary.search

search(query: str, top_k: int=5) -> list[ToolArtifact]

Parameter	Type	Default
query	str	required
top_k	int	5

Source

SqliteToolLibrary.deprecate

deprecate(name: str) -> bool

Parameter	Type	Default
name	str	required

Source

SqliteToolLibrary.close

close() -> None

Source

ToolLibraryError

from qitos.kit.tool.library.sqlite_store import ToolLibraryError

Source @ 19f6258

Usage and executable example

Usage fragment: continues with objects from the linked complete tutorial; not a standalone program.

# Catch ToolLibraryError and inspect error.code; do not infer success from absence of output.

Non-echoing library failure, identified by a stable code.

ToolLibraryError(code: str) -> Any (see behavior contract)

Parameter	Type	Default
code	str	required

MemdirMemory

from qitos.kit.memory.memdir_memory import MemdirMemory

Source @ 19f6258

Usage and executable example

Usage fragment: continues with objects from the linked complete tutorial; not a standalone program.

memory = MemdirMemory(private_memory_path, create=True)
# Subsequent processes reopen with create=False (the default).
removed = memory.delete(record_id)

Persist text records with stable identity and fresh disk retrieval.

Restore is the default and fails if a bound root is missing. Pass
``create=True`` only to explicitly initialize a namespace. ``reset`` and
``evict`` affect the append-time cache only; ``delete`` removes a local fact.
Arbitrary Python/JSON content and metadata are not a durable round-trip API.

MemdirMemory(memory_dir: str='.qitos/memory', *, global_memory_dir: str | None=None, create: bool=False, max_index_entries: int=200, max_index_chars: int=25000) -> Any (see behavior contract)

Parameter	Type	Default
memory_dir	str	'.qitos/memory'
global_memory_dir	str | None	None
create	bool	False
max_index_entries	int	200
max_index_chars	int	25000

MemdirMemory.append

append(record: MemoryRecord) -> None

Parameter	Type	Default
record	MemoryRecord	required

Source

MemdirMemory.retrieve

retrieve(query: Optional[Dict[str, Any]]=None, state: Any=None, observation: Any=None) -> List[MemoryRecord]

Parameter	Type	Default
query	Optional[Dict[str, Any]]	None
state	Any	None
observation	Any	None

Source

MemdirMemory.delete

delete(record_id: str) -> bool

Parameter	Type	Default
record_id	str	required

Forget one logical record in this namespace, never global memory.

Idempotent for an absent identity. This is local-file deletion, not
secure erasure or a concurrent multi-file transaction. Callers serialize
writes to one Memdir namespace; use a transactional backend otherwise.

Source