memside 0.2.0__tar.gz → 0.3.0__tar.gz

memside-0.3.0/PKG-INFO

@@ -0,0 +1,204 @@
+Metadata-Version: 2.4
+Name: memside
+Version: 0.3.0
+Summary: Python client for Memside AI continuity, portable context, checkpoints, operating rules, User AI Profile, and AI Skills.
+Author-email: Memside <support@memside.com>
+License-Expression: LicenseRef-Proprietary
+Project-URL: Homepage, https://github.com/memside/memside
+Project-URL: Repository, https://github.com/memside/memside
+Project-URL: Issues, https://github.com/memside/memside/issues
+Keywords: memside,ai,memory,mcp,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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: Programming Language :: Python :: 3.13
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Dynamic: license-file
+
+# Memside Python SDK
+
+Python client for Memside AI continuity, portable context, checkpoints, operating rules, User AI Profile, and AI Skills.
+
+## Install
+
+```bash
+pip install memside
+```
+
+## Usage
+
+```python
+from memside import MemsideClient
+
+client = MemsideClient(api_key="mem_sk_your_key_here")
+
+startup = client.context_startup()
+print(startup)
+```
+
+Create a memory with the public `type` and `text` fields:
+
+```python
+memory = client.memories_create(
+    {
+        "type": "note",
+        "text": "Packing checklist\nBring a charger and a reusable bottle.",
+        "sensitivity": "private",
+    }
+)
+```
+
+Use the current version when updating a Memory you previously read:
+
+```python
+updated = client.memories_update(
+    memory["id"],
+    {
+        "text": "Packing checklist\nBring a charger and a reusable bottle.",
+        "expected_version": memory["version"],
+    },
+)
+```
+
+Create a Subject and link a non-secret memory:
+
+```python
+subject = client.subjects_create(
+    {
+        "name": "Weekend reading",
+        "subject_type": "topic",
+        "aliases": ["Reading list"],
+    }
+)
+
+client.subjects_link_memory(subject["id"], memory["id"])
+context = client.subjects_get_context(subject["id"])
+```
+
+Read eligible Facts and propose a source-backed addition for user review:
+
+```python
+facts = client.subjects_list_facts(subject["id"])
+
+suggestion = client.subjects_suggest_fact(
+    subject["id"],
+    {
+        "suggestion_type": "add_fact",
+        "proposed_fact_type": "preference",
+        "proposed_fact_text": (
+            "Prefers printed books for long-form reading."
+        ),
+        "source_memory_id": memory["id"],
+        "idempotency_key": "reading-preference-v1",
+    },
+)
+```
+
+Fact Suggestions remain pending until a signed-in user reviews them. The SDK
+does not expose direct Fact mutation or suggestion review.
+
+Read a bounded Context Map and pending Memory Insights:
+
+```python
+context_map = client.memories_get_context_map(memory["id"])
+history = client.memories_get_revisions(memory["id"])
+insights = client.subjects_list_memory_insights(
+    subject["id"],
+    limit=25,
+)
+```
+
+Insight refresh, review, and undo remain signed-in application actions.
+
+Prepare Subject deletion without changing data:
+
+```python
+preview = client.subjects_prepare_delete(subject["id"])
+print(preview["required_confirmation"])
+```
+
+The SDK does not generate or submit Subject deletion confirmation
+automatically.
+
+Deletion requires the resource-specific confirmation returned by your
+application workflow:
+
+```python
+client.memories_delete(
+    memory["id"],
+    f"CONFIRM_DELETE_{memory['id']}",
+)
+```
+
+You can also set the API key through the environment:
+
+```bash
+MEMSIDE_API_KEY=mem_sk_your_key_here
+```
+
+## Supported API Areas
+
+This package wraps public Memside API-key routes:
+
+- startup context
+- resume context
+- workspace profile
+- memory listing
+- memory search
+- memory fetch
+- memory revision history
+- bounded exact-ID memory batch reads
+- bounded memory Context Maps
+- memory create
+- memory update
+- memory delete, when allowed by the API
+- Subject listing, creation, retrieval, and update
+- Subject-memory listing, linking, and unlinking
+- bounded Subject Context
+- eligible Subject Fact reads
+- source-backed Fact Suggestions for signed-in-user review
+- pending-only Memory Insight reads
+- guarded Subject deletion preparation and confirmation
+
+This package does not include private Memside application source, account/session internals, billing internals, admin routes, database details, or MCP server implementation.
+
+## API Reference
+
+| Area | Methods |
+| --- | --- |
+| Context | `context_startup`, `context_resume`, `context_workspace_profile` |
+| Memories | `memories_list`, `memories_search`, `memories_get`, `memories_get_batch`, `memories_get_revisions`, `memories_get_context_map`, `memories_list_subjects`, `memories_create`, `memories_update`, `memories_delete` |
+| Subjects | `subjects_list`, `subjects_create`, `subjects_get`, `subjects_update`, `subjects_list_memories`, `subjects_link_memory`, `subjects_unlink_memory`, `subjects_get_context`, `subjects_list_facts`, `subjects_suggest_fact`, `subjects_list_memory_insights`, `subjects_prepare_delete`, `subjects_delete` |
+
+See the curated
+[OpenAPI document](https://raw.githubusercontent.com/memside/memside/main/openapi.json)
+for public request and response fields.
+
+Public request and response shapes are exported as lightweight `TypedDict`
+definitions for editors and type checkers. Failed requests raise
+`MemsideError`, including `status`, `code`, `retryable`, `retry_after`,
+`request_id`, and safe `details`.
+
+For `429` responses, wait for `retry_after` before retrying a read. The SDK
+does not automatically retry writes.
+
+Eligible responses contain attachment metadata only. Raw attachment data,
+private storage locations, and signed download URLs are not returned through
+the public API-key contract.
+
+## Compatibility
+
+The package uses additive public methods and typed fields where possible.
+Breaking changes require a documented migration path. The client accepts the
+current public error envelope and documented legacy `detail` responses during
+the V2 compatibility period.
+
+## Requirements
+
+Python 3.9 or newer.

memside-0.3.0/README.md

@@ -0,0 +1,181 @@
+# Memside Python SDK
+
+Python client for Memside AI continuity, portable context, checkpoints, operating rules, User AI Profile, and AI Skills.
+
+## Install
+
+```bash
+pip install memside
+```
+
+## Usage
+
+```python
+from memside import MemsideClient
+
+client = MemsideClient(api_key="mem_sk_your_key_here")
+
+startup = client.context_startup()
+print(startup)
+```
+
+Create a memory with the public `type` and `text` fields:
+
+```python
+memory = client.memories_create(
+    {
+        "type": "note",
+        "text": "Packing checklist\nBring a charger and a reusable bottle.",
+        "sensitivity": "private",
+    }
+)
+```
+
+Use the current version when updating a Memory you previously read:
+
+```python
+updated = client.memories_update(
+    memory["id"],
+    {
+        "text": "Packing checklist\nBring a charger and a reusable bottle.",
+        "expected_version": memory["version"],
+    },
+)
+```
+
+Create a Subject and link a non-secret memory:
+
+```python
+subject = client.subjects_create(
+    {
+        "name": "Weekend reading",
+        "subject_type": "topic",
+        "aliases": ["Reading list"],
+    }
+)
+
+client.subjects_link_memory(subject["id"], memory["id"])
+context = client.subjects_get_context(subject["id"])
+```
+
+Read eligible Facts and propose a source-backed addition for user review:
+
+```python
+facts = client.subjects_list_facts(subject["id"])
+
+suggestion = client.subjects_suggest_fact(
+    subject["id"],
+    {
+        "suggestion_type": "add_fact",
+        "proposed_fact_type": "preference",
+        "proposed_fact_text": (
+            "Prefers printed books for long-form reading."
+        ),
+        "source_memory_id": memory["id"],
+        "idempotency_key": "reading-preference-v1",
+    },
+)
+```
+
+Fact Suggestions remain pending until a signed-in user reviews them. The SDK
+does not expose direct Fact mutation or suggestion review.
+
+Read a bounded Context Map and pending Memory Insights:
+
+```python
+context_map = client.memories_get_context_map(memory["id"])
+history = client.memories_get_revisions(memory["id"])
+insights = client.subjects_list_memory_insights(
+    subject["id"],
+    limit=25,
+)
+```
+
+Insight refresh, review, and undo remain signed-in application actions.
+
+Prepare Subject deletion without changing data:
+
+```python
+preview = client.subjects_prepare_delete(subject["id"])
+print(preview["required_confirmation"])
+```
+
+The SDK does not generate or submit Subject deletion confirmation
+automatically.
+
+Deletion requires the resource-specific confirmation returned by your
+application workflow:
+
+```python
+client.memories_delete(
+    memory["id"],
+    f"CONFIRM_DELETE_{memory['id']}",
+)
+```
+
+You can also set the API key through the environment:
+
+```bash
+MEMSIDE_API_KEY=mem_sk_your_key_here
+```
+
+## Supported API Areas
+
+This package wraps public Memside API-key routes:
+
+- startup context
+- resume context
+- workspace profile
+- memory listing
+- memory search
+- memory fetch
+- memory revision history
+- bounded exact-ID memory batch reads
+- bounded memory Context Maps
+- memory create
+- memory update
+- memory delete, when allowed by the API
+- Subject listing, creation, retrieval, and update
+- Subject-memory listing, linking, and unlinking
+- bounded Subject Context
+- eligible Subject Fact reads
+- source-backed Fact Suggestions for signed-in-user review
+- pending-only Memory Insight reads
+- guarded Subject deletion preparation and confirmation
+
+This package does not include private Memside application source, account/session internals, billing internals, admin routes, database details, or MCP server implementation.
+
+## API Reference
+
+| Area | Methods |
+| --- | --- |
+| Context | `context_startup`, `context_resume`, `context_workspace_profile` |
+| Memories | `memories_list`, `memories_search`, `memories_get`, `memories_get_batch`, `memories_get_revisions`, `memories_get_context_map`, `memories_list_subjects`, `memories_create`, `memories_update`, `memories_delete` |
+| Subjects | `subjects_list`, `subjects_create`, `subjects_get`, `subjects_update`, `subjects_list_memories`, `subjects_link_memory`, `subjects_unlink_memory`, `subjects_get_context`, `subjects_list_facts`, `subjects_suggest_fact`, `subjects_list_memory_insights`, `subjects_prepare_delete`, `subjects_delete` |
+
+See the curated
+[OpenAPI document](https://raw.githubusercontent.com/memside/memside/main/openapi.json)
+for public request and response fields.
+
+Public request and response shapes are exported as lightweight `TypedDict`
+definitions for editors and type checkers. Failed requests raise
+`MemsideError`, including `status`, `code`, `retryable`, `retry_after`,
+`request_id`, and safe `details`.
+
+For `429` responses, wait for `retry_after` before retrying a read. The SDK
+does not automatically retry writes.
+
+Eligible responses contain attachment metadata only. Raw attachment data,
+private storage locations, and signed download URLs are not returned through
+the public API-key contract.
+
+## Compatibility
+
+The package uses additive public methods and typed fields where possible.
+Breaking changes require a documented migration path. The client accepts the
+current public error envelope and documented legacy `detail` responses during
+the V2 compatibility period.
+
+## Requirements
+
+Python 3.9 or newer.

{memside-0.2.0 → memside-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "memside"
-version = "0.2.0"
+version = "0.3.0"
 description = "Python client for Memside AI continuity, portable context, checkpoints, operating rules, User AI Profile, and AI Skills."
 readme = "README.md"
 requires-python = ">=3.9"

memside-0.3.0/src/memside/__init__.py

@@ -0,0 +1,70 @@
+from .client import MemsideClient, MemsideError
+from .connected_context_types import (
+    ContextMap,
+    ContextMapMemoryNode,
+    MemoryInsight,
+    MemoryInsightEvidence,
+    MemoryInsightList,
+)
+from .subject_types import (
+    FactSuggestion,
+    FactSuggestionCreate,
+    FactType,
+    Subject,
+    SubjectContext,
+    SubjectCreate,
+    SubjectDeleteResult,
+    SubjectDeletionPreview,
+    SubjectFact,
+    SubjectFactList,
+    SubjectMemory,
+    SubjectMemoryLinkResult,
+    SubjectMemoryUnlinkResult,
+    SubjectUpdate,
+)
+from .types import (
+    Memory,
+    MemoryBatchResult,
+    MemoryCreate,
+    MemoryDeleteResult,
+    MemoryRevision,
+    MemoryRevisionList,
+    MemoryUpdate,
+    ResumeContext,
+    StartupContext,
+    WorkspaceProfile,
+)
+
+__all__ = [
+    "MemsideClient",
+    "MemsideError",
+    "ContextMap",
+    "ContextMapMemoryNode",
+    "FactSuggestion",
+    "FactSuggestionCreate",
+    "FactType",
+    "Subject",
+    "SubjectContext",
+    "SubjectCreate",
+    "SubjectDeleteResult",
+    "SubjectDeletionPreview",
+    "SubjectFact",
+    "SubjectFactList",
+    "SubjectMemory",
+    "SubjectMemoryLinkResult",
+    "SubjectMemoryUnlinkResult",
+    "SubjectUpdate",
+    "Memory",
+    "MemoryBatchResult",
+    "MemoryCreate",
+    "MemoryDeleteResult",
+    "MemoryRevision",
+    "MemoryRevisionList",
+    "MemoryUpdate",
+    "MemoryInsight",
+    "MemoryInsightEvidence",
+    "MemoryInsightList",
+    "ResumeContext",
+    "StartupContext",
+    "WorkspaceProfile",
+]

{memside-0.2.0 → memside-0.3.0}/src/memside/client.py

@@ -3,14 +3,30 @@ import os
 from typing import Iterable, List, Optional
 from urllib.error import HTTPError
 from urllib.parse import urlencode
-from urllib.request import Request, urlopen
-
-from .types import (
+from urllib.request import Request, urlopen
+
+from .connected_context_types import ContextMap, MemoryInsightList
+from .subject_types import (
+    FactSuggestion,
+    FactSuggestionCreate,
+    Subject,
+    SubjectContext,
+    SubjectCreate,
+    SubjectDeleteResult,
+    SubjectDeletionPreview,
+    SubjectMemory,
+    SubjectMemoryLinkResult,
+    SubjectMemoryUnlinkResult,
+    SubjectFactList,
+    SubjectUpdate,
+)
+from .types import (
     Memory,
     MemoryBatchResult,
     MemoryCreate,
-    MemoryDeleteResult,
-    MemoryUpdate,
+    MemoryDeleteResult,
+    MemoryRevisionList,
+    MemoryUpdate,
     ResumeContext,
     StartupContext,
     WorkspaceProfile,
@@ -70,9 +86,18 @@ class MemsideClient:
     def memories_search(self, **params) -> List[Memory]:
         return self.request("GET", "/memories/search", params=params)
 
-    def memories_get(self, memory_id: str) -> Memory:
-        return self.request("GET", f"/memories/{memory_id}")
-
+    def memories_get(self, memory_id: str) -> Memory:
+        return self.request("GET", f"/memories/{memory_id}")
+
+    def memories_get_revisions(self, memory_id: str) -> MemoryRevisionList:
+        return self.request("GET", f"/memories/{memory_id}/revisions")
+
+    def memories_get_context_map(self, memory_id: str) -> ContextMap:
+        return self.request("GET", f"/memories/{memory_id}/context-map")
+
+    def memories_list_subjects(self, memory_id: str) -> List[Subject]:
+        return self.request("GET", f"/memories/{memory_id}/subjects")
+
     def memories_get_batch(
         self,
         memory_ids: Iterable[str],
@@ -103,12 +128,127 @@ class MemsideClient:
             if delete_confirmation is not None
             else None
         )
-        return self.request(
-            "DELETE",
-            f"/memories/{memory_id}",
-            json_body=body,
-        )
-
+        return self.request(
+            "DELETE",
+            f"/memories/{memory_id}",
+            json_body=body,
+        )
+
+    def subjects_list(self, **params) -> List[Subject]:
+        return self.request("GET", "/subjects", params=params)
+
+    def subjects_create(self, subject: SubjectCreate) -> Subject:
+        return self.request("POST", "/subjects", json_body=subject)
+
+    def subjects_get(self, subject_id: str) -> Subject:
+        return self.request("GET", f"/subjects/{subject_id}")
+
+    def subjects_update(self, subject_id: str, patch: SubjectUpdate) -> Subject:
+        return self.request("PATCH", f"/subjects/{subject_id}", json_body=patch)
+
+    def subjects_list_memories(
+        self,
+        subject_id: str,
+        *,
+        include_archived: bool = False,
+        limit: int = 20,
+    ) -> List[SubjectMemory]:
+        return self.request(
+            "GET",
+            f"/subjects/{subject_id}/memories",
+            params={"include_archived": include_archived, "limit": limit},
+        )
+
+    def subjects_link_memory(
+        self,
+        subject_id: str,
+        memory_id: str,
+    ) -> SubjectMemoryLinkResult:
+        return self.request(
+            "POST",
+            f"/subjects/{subject_id}/memories",
+            json_body={"memory_id": memory_id},
+        )
+
+    def subjects_unlink_memory(
+        self,
+        subject_id: str,
+        memory_id: str,
+    ) -> SubjectMemoryUnlinkResult:
+        return self.request(
+            "DELETE",
+            f"/subjects/{subject_id}/memories/{memory_id}",
+        )
+
+    def subjects_get_context(
+        self,
+        subject_id: str,
+        **params,
+    ) -> SubjectContext:
+        return self.request(
+            "GET",
+            f"/subjects/{subject_id}/context",
+            params=params,
+        )
+
+    def subjects_list_facts(
+        self,
+        subject_id: str,
+        *,
+        include_history: bool = False,
+        limit: int = 50,
+    ) -> SubjectFactList:
+        return self.request(
+            "GET",
+            f"/subjects/{subject_id}/facts",
+            params={"include_history": include_history, "limit": limit},
+        )
+
+    def subjects_suggest_fact(
+        self,
+        subject_id: str,
+        suggestion: FactSuggestionCreate,
+    ) -> FactSuggestion:
+        return self.request(
+            "POST",
+            f"/subjects/{subject_id}/fact-suggestions",
+            json_body=suggestion,
+        )
+
+    def subjects_list_memory_insights(
+        self,
+        subject_id: str,
+        *,
+        limit: int = 50,
+    ) -> MemoryInsightList:
+        return self.request(
+            "GET",
+            f"/subjects/{subject_id}/memory-insights",
+            params={"status": "pending", "limit": limit},
+        )
+
+    def subjects_prepare_delete(self, subject_id: str) -> SubjectDeletionPreview:
+        return self.request(
+            "POST",
+            f"/subjects/{subject_id}/deletion/prepare",
+        )
+
+    def subjects_delete(
+        self,
+        subject_id: str,
+        delete_confirmation: Optional[str] = None,
+    ) -> SubjectDeleteResult:
+        body = (
+            {"delete_confirmation": delete_confirmation}
+            if delete_confirmation is not None
+            else None
+        )
+        return self.request(
+            "DELETE",
+            f"/subjects/{subject_id}",
+            json_body=body,
+        )
+
     def request(self, method, path, *, params=None, json_body=None, headers=None):
         url = self._build_url(path, params)
         request_headers = {