Metadata-Version: 2.4
Name: memoryintelligence
Version: 1.0.0
Summary: Official Python SDK for Memory Intelligence - Verifiable meaning infrastructure for AI
Author-email: Memory Intelligence Team <sdk@memoryintelligence.dev>
Maintainer-email: Memory Intelligence Team <sdk@memoryintelligence.dev>
License: MIT
Project-URL: Homepage, https://memoryintelligence.dev
Project-URL: Documentation, https://docs.memoryintelligence.dev
Project-URL: Repository, https://github.com/memoryintelligence/sdk-python
Project-URL: Changelog, https://github.com/memoryintelligence/sdk-python/blob/main/CHANGELOG.md
Keywords: ai,llm,memory,rag,embeddings,nlp,privacy,compliance,hipaa,gdpr,provenance
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Dynamic: license-file

## Memory Intelligence Python SDK

Official Python client for building applications, agents, integrations, and data pipelines on top of the Memory Intelligence OS.

The Python SDK provides a full-featured interface for interacting with the Memory Intelligence Operating System (MemoryOS).
It is optimized for:
	•	backend services
	•	data ingestion pipelines
	•	ML research & evaluation
	•	analytics & ETL
	•	agent development
	•	enterprise automation workflows

It supports both sync and async usage, enforces all governance + privacy rules, and provides high-level helpers for working with UMOs, search, timelines, clusters, provenance, and agents.

(This README supersedes and expands the minimal starter at:  ￼)

⸻

1. Features

Meaning-First API Surface
	•	Native UMO creation
	•	Semantic + hybrid search
	•	Timeline querying
	•	Graph neighborhood expansion
	•	Cluster & drift detection access
	•	Agent execution (summaries, insights, narratives)

Production-Ready Network Layer
	•	Sync + Async clients
	•	Automatic retries with exponential backoff
	•	Connection pooling
	•	Circuit-breaking & timeouts
	•	Request tracing (observability)
	•	Structured logging helpers

Governance + Privacy Enforcement
	•	Automatic conversion of external IDs → ULIDs
	•	Masking of governed fields
	•	Provenance hashing (SHA-256)
	•	Tenant isolation
	•	No raw identity leakage

Developer Ergonomics
	•	Type hints
	•	Pydantic models
	•	Exceptions for precise error handling
	•	Response validation
	•	Extensible middleware

Advanced SDK Extensions
	•	Bulk ingestion helpers
	•	Batch export helpers
	•	Local capture queue (offline-first ingestion)
	•	Evaluation tools for embeddings & search quality

⸻

2. Installation

pip install memory-intelligence

Or install from source for development:

pip install -e .


⸻

3. Initialization

from memory_intelligence import MemoryClient

client = MemoryClient(
    api_key="YOUR_API_KEY",
    api_url="https://api.memory-intelligence.com"
)

You may also configure via environment variables:

MI_API_KEY=...
MI_API_URL=https://api.memory-intelligence.com


⸻

4. Core Concepts

Unified Memory Objects (UMOs)

UMOs are the canonical memory format inside MemoryOS.

The SDK automatically validates UMO structure and can create them from:
	•	text
	•	audio transcription text
	•	images (OCR text)
	•	URLs (browser captures)
	•	JSON capture envelopes
	•	Slack/email ingestion payloads

The SDK ensures:
	•	correct schema
	•	correct timestamp formats
	•	correct ULID identity boundaries
	•	correct provenance hashing

⸻

5. Creating Memories

Simple Text Memory

umo = client.memories.create(
    content="Had a meeting about Q2 product roadmap.",
    tags=["meeting", "planning"]
)

With Additional Metadata

umo = client.memories.create(
    content="User feedback from onboarding session.",
    context={"channel": "support", "sentiment": "positive"},
    source="manual"
)

With Provenance Hash Override

umo = client.memories.create(
    content="Draft article notes.",
    provenance_hash="abc123...",  # optional if you compute your own
)


⸻

6. Searching Memories

Semantic Search

results = client.search.semantic("project planning")

Hybrid Search (semantic + lexical + temporal)

results = client.search.hybrid(
    query="customer retention initiative",
    limit=20,
)

Entity-Based Filtering

results = client.search.by_entity("OpenAI", limit=10)

Graph Neighborhood Expansion

neighbors = client.graph.neighbors(umo_id="01F...")


⸻

7. Timeline Queries

timeline = client.timeline.range(
    start="2025-01-01",
    end="2025-02-01",
    sort="chronological"
)

Or retrieve the significance-ranked resurfacing window:

resurfaced = client.timeline.resurface(limit=15)


⸻

8. Inspecting UMOs

umo = client.memories.get("01H...")    # fetch a UMO
print(umo.meaning.entities)            # inspect meaning
print(umo.provenance.hash)             # provenance integrity

Diffing UMO Versions

diff = client.memories.diff("01H...", version_a=1, version_b=3)


⸻

9. Agents API (Summaries, Insights, Narrative)

Generate a summary

summary = client.agents.summarize(umo_id="01H...")

Generate insights across a collection

insights = client.agents.generate_insights(collection_id="col_123")

Narrative generation

narrative = client.agents.narrative(umo_ids=["01H..", "01H.."])


⸻

10. Working With Collections

col = client.collections.create(name="Research Notes")

client.collections.add(
    collection_id=col.id,
    umo_id="01H..."
)

Fetch:

items = client.collections.get(col.id)


⸻

11. Async Usage

From the original file expanded:

import asyncio
from memory_intelligence import MemoryAsyncClient

async def main():
    async with MemoryAsyncClient(api_key="YOUR_KEY") as client:
        results = await client.search.semantic("product planning")
        print(results)

asyncio.run(main())

Async client supports:
	•	connection pooling
	•	concurrent searches
	•	async streaming (roadmap)

⸻

12. Bulk & Batch Operations

Batch Ingestion

batch = [
    {"content": "Interview notes …"},
    {"content": "Email summary …"},
    {"content": "Research excerpt …"},
]

client.bulk.ingest(batch)

Batch Export

data = client.bulk.export(
    since="2024-01-01",
    include_provenance=True
)


⸻

13. Error Handling

from memory_intelligence.errors import (
    AuthenticationError,
    ValidationError,
    GovernanceViolation,
    RateLimitExceeded,
    ServerError
)

try:
    client.memories.create(content=None)
except ValidationError as e:
    print("Invalid memory:", e)

Each exception type includes:
	•	error code
	•	human-friendly message
	•	context metadata
	•	retry hints (when applicable)

⸻

14. Observability & Logging

Attach middleware:

from memory_intelligence.middlewares import LoggingMiddleware

client = MemoryClient(
    api_key="...",
    middlewares=[LoggingMiddleware()]
)

Each request emits:
	•	trace_id
	•	span_id
	•	duration_ms
	•	HTTP code
	•	retry count (if applicable)

Compatible with:
	•	OpenTelemetry
	•	Datadog
	•	New Relic

⸻

15. Governance Compliance in the SDK

The SDK automatically:
	•	strips forbidden identity fields
	•	maps external IDs → ULIDs
	•	masks governed entities
	•	prevents raw external identifiers from being sent
	•	computes SHA-256 provenance hashes
	•	prevents accidental schema violations

This guarantees MemoryOS receives clean, safe, meaning-aligned data.

⸻

16. Local Capture Queue (Optional)

For offline or burst ingestion:

queue = client.capture_queue()

queue.enqueue({"content": "Field note"})
queue.enqueue({"content": "Another note"})

queue.flush()  # uploads in batches

Provides:
	•	crash-safe local disk persistence
	•	idempotent sync
	•	backpressure control

⸻

17. Development Utilities

Validate a UMO

from memory_intelligence import validate_umo

validate_umo(umo_dict)

Encode/Decode ULIDs

from memory_intelligence import ULID

ulid = ULID.new()

Compute a provenance hash

from memory_intelligence import compute_hash

h = compute_hash("some content")


⸻

18. Roadmap

Upcoming Python SDK features:
	•	streaming search results
	•	async agent pipelines
	•	local meaning snapshot cache
	•	automatic retry queues
	•	timeline diff utilities
	•	embedding evaluation toolkit

⸻

19. Summary

The Memory Intelligence Python SDK is the foundation for:
	•	ingestion pipelines
	•	application backends
	•	research tooling
	•	enterprise workflows
	•	agent development
	•	governance-safe meaning retrieval

It abstracts the complexity of MemoryOS, Engines, Identity, Governance, and Platform layers—providing a meaning-first, privacy-first, developer-friendly interface for building the next generation of memory-driven applications.

⸻
