mark-sdk 0.2.0a5__tar.gz

mark_sdk-0.2.0a5/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,53 @@
+name: Bug report
+description: Something in mark-sdk doesn't work as documented
+title: "[bug]: "
+labels: ["bug", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time — bug reports like yours are how MARK gets solid.
+        Two minutes of detail here usually saves days of back-and-forth.
+  - type: input
+    id: version
+    attributes:
+      label: mark-sdk version
+      placeholder: "0.2.0a5  (python -c 'import mark; print(mark.__version__)')"
+    validations:
+      required: true
+  - type: input
+    id: python
+    attributes:
+      label: Python version and OS
+      placeholder: "Python 3.12 on Ubuntu 24.04"
+    validations:
+      required: true
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: What did you do, what did you expect, what happened instead?
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Minimal reproduction
+      description: Smallest snippet that shows the problem. Use a temp directory if it involves the store.
+      render: python
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Traceback / output
+      render: text
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Checks
+      options:
+        - label: I searched existing issues first
+          required: true
+        - label: This report contains no secrets or private data
+          required: true

mark_sdk-0.2.0a5/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Question / discussion
+    url: https://github.com/emsoftanalytics/MARK-SDK/discussions
+    about: Ask usage questions or share what you're building with MARK.
+  - name: Security report (private)
+    url: https://github.com/emsoftanalytics/MARK-SDK/security/advisories/new
+    about: Please report vulnerabilities privately, never as public issues.

mark_sdk-0.2.0a5/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,33 @@
+name: Feature request
+description: Suggest an improvement to the local SDK
+title: "[feature]: "
+labels: ["enhancement", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Ideas welcome — especially ones grounded in a real agent workload you're building.
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem are you trying to solve?
+      description: Describe the agent/memory workflow where the SDK falls short.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: What would you like MARK to do?
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: What are you doing today instead?
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Checks
+      options:
+        - label: This fits the local-first SDK (works offline, no required services)
+          required: false

mark_sdk-0.2.0a5/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,15 @@
+## What does this PR do?
+
+<!-- One or two sentences. Link the issue it fixes: Fixes #123 -->
+
+## How was it tested?
+
+- [ ] `uv run pytest` passes locally
+- [ ] New behavior is covered by a test
+- [ ] Docstrings updated where behavior changed
+
+## Checklist
+
+- [ ] Core stays local-first (no new required dependencies or network calls)
+- [ ] Schema changes include a `_MIGRATIONS` entry and a migration test
+- [ ] No secrets, keys, or private data in the diff

mark_sdk-0.2.0a5/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv run --extra dev pytest
+
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv build
+      - run: |
+          # Shipped artifacts must not contain tests, tutorials, or planning docs.
+          ! unzip -l dist/*.whl | grep -E "tests/|tutorial|PLAN\.md"

mark_sdk-0.2.0a5/.github/workflows/release.yml

@@ -0,0 +1,57 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv run --extra dev pytest
+
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv build
+      - run: |
+          ! unzip -l dist/*.whl | grep -E "tests/|tutorial|PLAN\.md|__pycache__|\.pyc|\.env|\.venv"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/*
+
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: build
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+      - uses: astral-sh/setup-uv@v6
+      - run: uv publish

mark_sdk-0.2.0a5/.gitignore

@@ -0,0 +1,80 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+.venv/
+venv/
+
+# Node / frontend
+node_modules/
+.next/
+out/
+coverage/
+*.tsbuildinfo
+
+# Keep this repository scoped to the Python MARK SDK package.
+/typescript/
+/python/mark-cloud/
+/python/mark-adapters/
+/mark-cloud/
+/mark-adapters/
+
+# Local MARK/runtime state
+.mark/
+mark_runs/
+mark_runs_test/
+
+# Proprietary planning and system design documentation
+history/
+**/PLAN.md
+docs/
+*.design.md
+*.architecture.md
+*.roadmap.md
+*proposal*.md
+*overview*.md
+recent-thoughts.md
+memory.md
+
+# Environment and secrets
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+*.crt
+
+# Editors and OS
+.vscode/
+.idea/
+Thumbs.db
+.DS_Store
+
+# Logs and temp files
+*.log
+tmp/
+temp/
+
+# Infrastructure state
+.terraform/
+*.tfstate
+*.tfstate.*
+
+# Generated notebooks
+.ipynb_checkpoints/
+.aiStoryTeller/
+# SDK tutorial run artifacts and local review output
+tutorial.py
+tutorial_mcp_server.py
+tutorial_output/
+review.json
+mark_tutorial_runs/
+tools/ab/results.json

mark_sdk-0.2.0a5/AGENTS.md

@@ -0,0 +1,65 @@
+# MARK Python SDK Agent Guide
+
+This package implements the local-first MARK SDK. When working in this package, treat MARK as the agent cognitive runtime: local memory, context assembly, policies, skills, and agent wrapping.
+
+## Product Boundary
+
+- `mark` is local-first and must work without network, Docker, cloud accounts, or hosted APIs.
+- `mark-cloud` owns HTTP/cloud sync, auth, tenancy, and hosted control-plane behavior.
+- `mark-adapters` owns LangChain, MCP, LangGraph, and framework-specific integrations.
+- Do not turn `mark` into a presentation app or product UI.
+
+## Agent Usage Pattern
+
+When demonstrating MARK usage, show the same task without MARK and with MARK.
+
+When MARK is active, treat it as persistent working memory, not an optional lookup step. The intended loop is:
+
+- recall from MARK before planning,
+- ground memory against current evidence,
+- act with remembered context,
+- reflect on durable outcomes,
+- remember verified facts, decisions, and procedures for future agents.
+
+Use MARK to improve:
+
+- recall: stored project facts are retrieved,
+- planning: steps are grounded in project context,
+- reasoning: decisions cite known constraints,
+- continuity: durable outcomes are written back.
+
+## SDK Integration Modes
+
+Agents should be able to use MARK as:
+
+- direct runtime: `Mark.local()` and `mark.wrap_agent(...)`,
+- tool: callable retrieval/write functions,
+- skill: `src/mark/skills/mark-usage/SKILL.md`,
+- MCP: protocol server exposing retrieve/write/list operations,
+- middleware: context retrieval before model/tool execution and memory writeback after accepted outcomes.
+
+Middleware and direct runtime examples should make MARK feel natural: the agent should receive context before it reasons and save durable outcomes after the task is accepted.
+
+## Development Rules
+
+- Keep local SDK dependencies minimal.
+- Add tests with every behavioral change.
+- Do not require LangChain, MCP, or cloud packages in the local SDK core.
+- Optional examples may mention LangChain, but local tests must run without provider API keys.
+- Do not store secrets in examples or memory fixtures except fake redaction test values.
+- Package non-Python skill assets explicitly so installed users can load them through `importlib.resources`.
+
+## Verification
+
+From `sdk/python/mark`, run:
+
+```bash
+uv run --extra dev pytest
+uv build
+```
+
+Before committing, verify the package contains the MARK usage skill:
+
+```bash
+uv run python -B -c "from importlib.resources import files; print(files('mark.skills').joinpath('mark-usage/SKILL.md').read_text().splitlines()[1])"
+```

mark_sdk-0.2.0a5/ARCHITECTURE.md

@@ -0,0 +1,250 @@
+# MARK Python SDK Architecture
+
+The MARK Python SDK is a local-first runtime for agent memory. It is the open,
+MIT-licensed layer that helps agents recall project facts, organize working
+context, and expose memory to tools, middleware, and framework adapters.
+
+Everything documented here runs locally. Hosted MARK services are separate
+products that connect through the SDK's public plugin hooks; their design is
+out of scope for this document.
+
+## Entrypoints
+
+### `Mark.local()`
+
+`Mark.local()` is the public entrypoint for local use cases.
+
+It is designed for:
+
+- tutorials and quick scripts,
+- lightweight coding agents,
+- local project memory,
+- SQLite persistence in `.mark/memory.db`,
+- direct use as a tool, middleware helper, or agent wrapper.
+
+It wires:
+
+- `MarkRuntime.local()` as the runtime engine,
+- `SimpleMemory` as the ergonomic block/retrieve surface,
+- `ContextBuilder`,
+- `PolicyRegistry`,
+- `SkillRegistry`,
+- `MarkAgent`.
+
+```python
+from mark import Mark
+
+with Mark.local(".") as mark:
+    mark.memory.block("project").write("The API framework is FastAPI.")
+    print(mark.memory.retrieve("Which API framework?").as_text())
+```
+
+Advanced path:
+
+```python
+with Mark.local(".") as mark:
+    agent = mark.runtime.memory("coder")
+    agent.store_sync("FastAPI handles routing.")
+    mark.runtime.run_cycle("coder")          # consolidate + deduplicate + prune
+    mark.runtime.integrity_check()           # []
+```
+
+### `MarkRuntime.local()`
+
+`MarkRuntime.local()` is the explicit runtime engine. Most developers should
+start with `Mark.local()`, but framework integrations and advanced
+applications can use `MarkRuntime` directly.
+
+It wires:
+
+- `LocalMemoryStore` with SQLite,
+- `HashEmbeddingProvider` or developer-provided `EmbeddingProvider`,
+- `VectorIndex`,
+- `RetrievalPipeline`,
+- `PluginRegistry`,
+- `MarkMemory`,
+- `GlobalMemoryBus`,
+- `TrustAwareGlobalMemoryBus`,
+- `LocalTracer`,
+- `GovernanceAuditLog`.
+
+## Memory Model
+
+```text
+fragment  → atomic evidence (content, session, tags, importance, confidence)
+node      → semantic anchor built from fragments (character, fact, location…)
+edge      → directed, typed, weighted relation between nodes
+block     → bounded set of fragments, nodes, and the edges between them
+chain     → blocks sealed and linked forward/backward per agent
+```
+
+An agent owns a namespace. Sessions partition it (`session_id`,
+`session_prefix`), tags narrow it, and blocks group it into inspectable units.
+
+### Memory Blocks And Provenance
+
+Blocks are graph containers: a block can represent a topic within a session,
+an entire session, or a world-bible scope.
+
+- Node membership is many-to-many (`block_nodes`), so canonical entities are
+  never duplicated across blocks.
+- Edges may be scoped to a block; scoped edges only connect member nodes.
+- Blocks connect to other blocks through directed `BlockLink`s and are
+  traversable forward and backward, like nodes through edges.
+- Sealing (`BlockChain.seal`) computes a deterministic SHA-256 content hash
+  over immutable member fields and links the block to the previously sealed
+  block (`prev_block_hash`), forming a local, tamper-evident hash chain.
+- `verify()` pinpoints corrupted, missing, or injected members;
+  `verify_chain()` checks the whole chain.
+- Quarantining a block removes its members from retrieval and traversal
+  without affecting any other block or the agent's function.
+- Mutable plasticity fields (importance, access counts, edge weights) are
+  excluded from hashes so reinforcement never breaks a seal.
+
+## Lifecycle
+
+| Method | Role |
+|---|---|
+| `working_memory(agent_id)` | TTL-bound short-term memory |
+| `consolidate(agent_id)` | Governed working-memory promotion |
+| `deduplicate(agent_id)` | Embedding cluster merge and provenance |
+| `prune(agent_id)` | Decay, fragment pruning, edge dissolution |
+| `run_cycle(agent_id)` | Consolidate, deduplicate, prune |
+| `integrity_check()` | SQLite health check |
+
+Retrieval is live. Each retrieved fragment is touched, access count increases,
+importance can strengthen through Hebbian reinforcement, and co-retrieved graph
+edges strengthen through co-activation. Promoted/permanent memories are exempt
+from decay.
+
+Consolidation is governed locally before promotion. `ConsolidationGate` redacts
+common secrets/PII, blocks empty or low-confidence content, rejects failure
+artifacts, and can reject exact duplicate hashes. `MarkRuntime` keeps an
+in-process `GovernanceAuditLog`.
+
+Deduplication is transparent and local. The SDK clusters stored embeddings,
+keeps the highest-importance canonical fragment, records `merged_from_ids`,
+and reattaches graph nodes from deleted duplicates to the kept fragment.
+
+## Architecture Diagram
+
+```mermaid
+flowchart TD
+    Dev[Developer Agent] --> Simple["Mark.local()"]
+
+    Simple --> SM[SimpleMemory]
+    Simple --> Skills[SkillRegistry]
+    Simple --> Policies[PolicyRegistry]
+    Simple --> Agent[MarkAgent]
+    Simple --> RT[MarkRuntime]
+
+    SM --> RT
+    RT --> SQLite[(LocalMemoryStore SQLite)]
+    RT --> Embeddings[EmbeddingProvider]
+    RT --> Vector[VectorIndex]
+    RT --> Retrieval[RetrievalPipeline]
+    RT --> Blocks[BlockGraph / BlockChain]
+    RT --> Bus[GlobalMemoryBus]
+    RT --> TrustBus[TrustAwareGlobalMemoryBus]
+    RT --> Obs[LocalTracer]
+    RT --> Governance[Local Governance]
+    RT --> Plugins[PluginRegistry]
+    RT --> Lifecycle[Lifecycle]
+
+    Retrieval --> Hebbian[Hebbian Reinforcement]
+    Lifecycle --> Consolidation[ConsolidationManager]
+    Lifecycle --> Dedup[DeduplicationConsolidator]
+    Lifecycle --> Pruner[MemoryPruner]
+    Consolidation --> Governance
+```
+
+## Package Boundary
+
+This package includes:
+
+- memory data contracts,
+- SQLite storage with schema versioning and in-place migrations,
+- local retrieval, graph expansion, and gap reporting,
+- graph-scoped memory blocks, block links, seal/verify, and quarantine,
+- working memory, governed consolidation, deduplication, and pruning,
+- graph nodes, edges, neighborhoods, and graph-connected context,
+- session-aware retrieval and session activity logs,
+- local governance heuristics and in-process audit logs,
+- local observability events, session traces, and JSONL replay,
+- local sync delta preparation with redaction,
+- trust-aware global memory bus,
+- plugin interfaces and hook constants,
+- optional framework adapters and skills.
+
+Hosted services, managed infrastructure, and commercial features are not part
+of this package. The only paths from the SDK outward are `PluginRegistry`
+hooks and clients that the developer explicitly supplies.
+
+## Tool, Middleware, And Adapters
+
+MARK can be used in three common ways:
+
+- As a tool: the agent explicitly calls MARK retrieval.
+- As middleware: MARK injects relevant memory before agent planning and records
+  observations after tool/action results.
+- As an MCP server: `mark.adapters.mcp` exposes local memory operations to any
+  MCP-compatible client.
+
+Framework adapters ship inside `mark-sdk` under `mark.adapters` with optional
+dependency extras:
+
+```text
+mark/
+  adapters/
+    backend.py    MarkBackend protocol + LocalMarkBackend
+    langchain/    tools + AgentMiddleware
+    mcp/          MCP server factory
+```
+
+```bash
+pip install "mark-sdk[langchain]"
+pip install "mark-sdk[mcp]"
+pip install "mark-sdk[adapters]"
+```
+
+Adapter modules are thin framework glue over public MARK APIs. Adapter
+namespaces without complete implementations are excluded from distributions
+until they have real code and tests.
+
+## Sync And Observability
+
+The SDK can prepare local sync envelopes but does not implement any remote
+transport. `CloudSync.prepare_delta()` returns a `SyncDelta` containing
+redacted fragments, optional local events, options, and stats.
+`CloudSync.sync()` forwards that envelope only when a caller supplies a client
+object with `upload_delta(delta)`.
+
+```mermaid
+flowchart LR
+    Runtime[MarkRuntime] --> Store[(SQLite)]
+    Runtime --> Tracer[LocalTracer]
+    Store --> Prepare[CloudSync.prepare_delta]
+    Tracer --> Prepare
+    Prepare --> Delta[SyncDelta]
+    Delta --> OptionalClient[Developer-supplied client]
+```
+
+`LocalTracer` is available through `MarkRuntime.tracer()`, and
+`MarkRuntime.session_trace(session_id)` provides a session-scoped view of
+local events.
+
+## Trust-Aware Bus
+
+`TrustAwareGlobalMemoryBus` wraps `GlobalMemoryBus` with publisher trust,
+subscriptions, snapshots, and trust-filtered retrieval. Messages persist as
+global-bus fragments with trust tags and can be rehydrated when a runtime
+reopens the same SQLite store.
+
+```mermaid
+flowchart TB
+    Publisher[Agent Publisher] --> TrustBus[TrustAwareGlobalMemoryBus]
+    TrustBus --> Store[(SQLite Global Fragments)]
+    TrustBus --> Snapshot[BusSnapshot]
+    TrustBus --> Subscription[BusSubscription]
+    Subscription --> Consumer[Consumer Agent]
+```