artha-engine 0.1.2

Semantic memory engine with append-only event ledger, Arthaanu representations, and projection replay.

Artha Engine

Artha Engine is the core Python library for building Arthaanu-based memory systems. It provides:

• typed Arthaanu representations
• encoder, lifecycle, decoder, and projection registries
• an append-only semantic event ledger
• SQLite and in-memory stores
• projection replay with watermarks and status
• typed product actions exposed as HTTP, MCP, and CLI tools
• Clerk/JWT/API-key authentication adapters
• portable OCI application builds
• a small artha CLI for inspection and local operation

The engine is intentionally small. Product-specific memory types, profiles, retrieval policy, and domain projections should usually live in userland packages built on top of the engine.

Install Locally

From this repository:

cd artha_engine
uv sync
uv run artha doctor

To run the FastAPI runtime:

uv sync --extra server
uv run artha serve --port 8765

Create product actions with one typed declaration:

@actions.action(
    name="memory.search",
    http=("POST", "/memories/search"),
    mcp=True,
    cli="memory search",
    scopes=["memory:read"],
)
def search(input: SearchInput, context: ActionContext) -> SearchOutput:
    ...

CLI

artha doctor
artha registry
artha encode text --input "Artha keeps semantic events canonical."
artha events --limit 5
artha objects --limit 5
artha projections
artha check
artha build

Use --db path/to/artha.db to point commands at a specific SQLite ledger. Most commands support --json for agent-friendly output.

Application CLIs generated from @actions.action(..., cli=...) also support remote mode:

memuron --base-url https://api.example.app --api-key arth_sk_... memory search --query postgres
memuron config set --base-url https://api.example.app --api-key arth_sk_...

Remote mode calls the action's HTTP route instead of requiring a local database. Install artha-engine[app] (or your product package with the same extra) for httpx support.

Managed API keys

Products can enable per-tenant API keys with one application hook:

from artha_engine import ArthaApplication, CompositeAuthProvider, ClerkAuthProvider
from artha_engine.app.managed_api_keys import ManagedApiKeyAuthProvider

application = ArthaApplication(...)
store = application.enable_managed_api_keys()
application.auth_provider = CompositeAuthProvider(
    primary=ClerkAuthProvider(),
    fallback=ManagedApiKeyAuthProvider(store=store),
)

This registers:

POST   /api-keys
GET    /api-keys
DELETE /api-keys/{key_id}

Keys are returned once on create (arth_sk_...), stored hashed, scoped, and tenant-bound. A bootstrap ARTHA_API_KEY env var still works for ops scripts.