memuron 0.1.1__py3-none-any.whl

memuron-0.1.1.dist-info/METADATA

@@ -0,0 +1,242 @@
+Metadata-Version: 2.3
+Name: memuron
+Version: 0.1.1
+Summary: Arthaanu application built on Artha Engine.
+Requires-Dist: artha-engine[auth,mcp,app]>=0.1.3
+Requires-Dist: agno>=2.3.11
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: uvicorn[standard]>=0.34.0
+Requires-Dist: psycopg[binary]>=3.2.0
+Requires-Dist: psycopg-pool>=3.3.1
+Requires-Dist: pyjwt>=2.10.0
+Requires-Dist: email-validator>=2.2.0
+Requires-Dist: pypdf>=6.0.0
+Requires-Dist: python-multipart>=0.0.20
+Requires-Dist: requests>=2.34.0
+Requires-Dist: pymupdf>=1.23
+Requires-Dist: python-docx>=1.1.0
+Requires-Dist: openpyxl>=3.1.5
+Requires-Dist: python-pptx>=1.0.2
+Requires-Dist: xlrd>=2.0.2
+Requires-Dist: olefile>=0.47
+Requires-Dist: svix>=1.40.0
+Requires-Dist: boto3>=1.35.0
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# memuron
+
+An Arthaanu application built on Artha Engine.
+
+**Documentation:** see [`docs/`](./docs/README.md) for architecture, rich nodes, document ingest, Guardian/spaces, frontend workbench, deployment, [Railway agent deploy guide](./docs/railway-deploy.md), and troubleshooting.
+
+## Mental Model
+
+Keep the engine small and generic. Put product memory behavior here:
+
+- custom Arthaanu types in `memuron/representations.py`
+- encoders that turn raw product input into meaning objects
+- lifecycle steps that normalize, merge, dedupe, or retire objects
+- projections that replay the event ledger into fast read models
+- decoders/API routes that expose product-specific reads
+
+The semantic event ledger is canonical. Projections are derived and rebuildable.
+
+Memuron writes product semantics into that ledger, but keeps the engine model clean:
+
+- memory create/update events stay product-specific: `memory.created`, `memory.updated`
+- memory/link deletes use the canonical engine event type `delete`
+- Memuron-specific delete meaning lives in metadata as `domain_event_type = memory.deleted` or `link.removed`
+- request identity is audit metadata, not hidden global state
+
+## Database
+
+Production uses **PostgreSQL** (Railway project `talented-exploration`).
+
+| Variable | Purpose |
+|----------|---------|
+| `ARTHA_DATABASE_URL` | PostgreSQL DSN for ledger + projections (preferred) |
+| `ARTHA_DB_PATH` | Fallback SQLite path for local-only dev |
+| `OPENROUTER_API_KEY` | OpenRouter key for Agno Guardian writes |
+| `GUARDIAN_MODEL` | Guardian LLM model (default: `inception/mercury-2`) |
+| `ARTHA_EMBEDDER` | `fastembed` (default) or `deterministic` |
+| `ARTHA_EMBED_MODEL` | Nomic embed model (default: `nomic-ai/nomic-embed-text-v1.5-Q`) |
+| `MEMURON_API_KEY` | Optional API key for `/memuron/*` and `/engine/*` routes |
+
+Copy `.env.example` to `.env` and set `ARTHA_DATABASE_URL` to the Railway **public** Postgres URL for local development.
+
+## Run
+
+Use **two terminals**, both starting from the **memuron repo root** (`Documents/memuron`), not `frontend/`.
+
+**Terminal 1 — backend**
+
+```bash
+cd /Users/rakshithg/Documents/memuron
+./scripts/dev-backend.sh
+# or manually:
+# source .env && uv run uvicorn memuron.application.api:create_app --factory --host 127.0.0.1 --port 8767
+```
+
+**Terminal 2 — frontend**
+
+```bash
+cd /Users/rakshithg/Documents/memuron
+./scripts/dev-frontend.sh
+# or: cd frontend && npm run dev
+```
+
+Open http://localhost:3000 — the workbench proxies to `http://127.0.0.1:8767/engine`; Memories uses `http://127.0.0.1:8767/memuron`.
+
+`frontend/.env.local` must use the **`/engine` suffix**:
+
+```bash
+ARTHA_ENGINE_URL=http://127.0.0.1:8767/engine
+MEMURON_API_URL=http://127.0.0.1:8767/memuron
+```
+
+If you see **502** on `/api/engine/*`, the backend is not running or the URL is wrong. Do not run `source .env` or `uv run` from inside `frontend/` — `.env` lives in the repo root and `uv` must use the memuron project.
+
+```bash
+uv sync
+cp .env.example .env   # then edit ARTHA_DATABASE_URL
+uv run pytest          # fast local suite (SQLite, skips integration)
+uv run pytest -m integration  # Postgres job queue + live Guardian (needs .env)
+uv run artha doctor
+```
+
+## MCP and CLI
+
+The stdio MCP server is intentionally restricted to one explicit Clerk user
+and organization. Configure its identity before starting it:
+
+```bash
+export MEMURON_MCP_ACTOR_ID=user_...
+export MEMURON_MCP_TENANT_ID=org_...
+export MEMURON_MCP_SCOPES=memory:read,memory:write,memory:delete,space:admin
+uv run memuron-mcp
+```
+
+The compact MCP surface centers on `memuron_help` and `memuron_query`, with
+memory ingest/get/update/delete/job polling and the complete space lifecycle.
+`memuron_document_source` resolves a document, chunk, image, or document
+collection node to the original uploaded file metadata and a short-lived
+download URL.
+Lower-level graph, list, collection, and bulk operations remain available
+through HTTP and the broader CLI without overwhelming an agent's tool picker.
+`memuron_get` bounds content by default and supports field selection, while
+`memuron_update` exposes flat `memory_id`, `content`, and `scope` arguments.
+Space arguments accept UUIDs, slugs, `space.*` tokens, and `/spaces/space.*`
+paths.
+
+```bash
+uv run memuron --help
+uv run memuron --tenant-id org_... query \
+  --cwd /spaces/space.personal \
+  --query 'semantic "deployment decisions" | head 5'
+uv run memuron --tenant-id org_... space list
+```
+
+All direct-ID operations verify that the target belongs to the active
+organization. API-key and local CLI callers must therefore provide a tenant.
+
+For editor login/logout, use the Railway-hosted Streamable HTTP endpoint:
+
+```json
+{
+  "mcpServers": {
+    "memuron": {
+      "url": "https://memuron-production.up.railway.app/mcp"
+    }
+  }
+}
+```
+
+Cursor discovers Clerk through OAuth protected-resource metadata, opens the
+Clerk consent flow, and stores its own access and refresh tokens. The OAuth
+application only needs the standard `profile` scope. Memuron resolves the
+signed-in user's Clerk organization membership server-side and maps it to the
+configured Memuron tenant. Enable Dynamic client registration in the Clerk
+Dashboard under OAuth applications so MCP clients can register with PKCE
+automatically.
+
+For users who belong to several mapped Clerk organizations, set
+`MEMURON_MCP_DEFAULT_CLERK_ORG_ID` to select one explicitly when the OAuth token
+does not carry an active organization.
+
+### Document storage
+
+Memuron keeps the searchable document graph in Postgres: normalized markdown,
+chunks, embeddings, links, metadata, and append-only events. Original uploads
+and extracted binary assets belong in S3-compatible object storage. This hybrid
+boundary preserves transactional graph queries without turning Postgres into a
+binary file store.
+
+## API (prefix `/memuron`)
+
+Core routes (see [`docs/README.md`](./docs/README.md) for full detail):
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/memories` | Create memory (async Guardian ingest, returns job id) |
+| POST | `/nodes` | Rich node (text / image / document / collection) + optional auto-link |
+| POST | `/documents/ingest` | Multipart file → collection + source + chunks + filtered images |
+| POST | `/collections` | Collection node |
+| POST | `/collections/{id}/placements` | Place member in collection |
+| GET | `/collections/{id}/members` | List collection members |
+| GET | `/graph/export` | Graph for UI |
+| GET | `/memories` | List memories (`scope`, `limit`, `offset`) |
+| POST | `/memories/search` | Semantic search (`query`, `k`, optional `scope`) |
+| GET | `/memories/{id}` | Get one memory |
+| POST | `/memories/batch` | Get many by id |
+| PUT | `/memories/{id}` | Update content/scope (sync, no Guardian) |
+| DELETE | `/memories/{id}` | Delete one memory |
+| POST | `/memories/bulk-delete` | Delete by scope filter |
+| POST | `/memories/unlink` | Remove link between two memories |
+| GET | `/memories/count` | Count with optional filters |
+| GET | `/jobs/{id}` | Poll async ingest job status |
+| GET | `/spaces` | List org spaces |
+
+## Auth and Audit Metadata
+
+Memuron uses bring-your-own API-key auth at the product boundary. When `MEMURON_API_KEY` is set, protected routes accept either:
+
+```text
+Authorization: Bearer <key>
+X-Memuron-Api-Key: <key>
+```
+
+Optional audit headers are copied into semantic event metadata:
+
+```text
+X-Memuron-Actor-Id: agent_123
+X-Memuron-Tenant-Id: workspace_456
+X-Memuron-Scopes: memory:write,memory:delete
+X-Request-Id: req_abc
+```
+
+This applies to Memuron writes and to the mounted Artha Engine API under `/engine`. The engine remains auth-provider agnostic; Memuron decides how API keys, actors, tenants, and scopes map to product permissions.
+
+The mounted engine exposes profile discovery at:
+
+```text
+GET /engine/runtime/capabilities
+```
+
+Example create → read flow:
+
+```bash
+# Create (async)
+curl -s -X POST http://127.0.0.1:8767/memuron/memories \
+  -H 'Content-Type: application/json' \
+  -d '{"content":"User enjoys rock climbing on weekends.","scope":["fitness.climbing"]}'
+
+# Poll job until completed, then read
+curl -s http://127.0.0.1:8767/memuron/memories/{memory_id}
+
+# List and search
+curl -s 'http://127.0.0.1:8767/memuron/memories?limit=20'
+curl -s -X POST http://127.0.0.1:8767/memuron/memories/search \
+  -H 'Content-Type: application/json' \
+  -d '{"query":"rock climbing","k":5}'
+```

memuron-0.1.1.dist-info/RECORD

@@ -0,0 +1,74 @@
+memuron/__init__.py,sha256=B7RUbuIzYVRBKVygo7DtGLkwIPHc8l9ZvyQTKtS3KnQ,86
+memuron/actions/__init__.py,sha256=0E9guFn3cve6XZGKkIIAYC1yEkkJPHNJzfdthg6jvR0,596
+memuron/actions/context.py,sha256=H8HRj8E5Ns4HDYad5nbywAOOWFsos3xK1c-amf63Iww,2141
+memuron/actions/helpers.py,sha256=m9pu5-KT3YlxcTX2AYYfePuNCCkZsmVpqgzkmFW0Lp8,2915
+memuron/actions/memory.py,sha256=inzsCA7V5evWPnHfLPPgVoIVMgjkVCivBRdl9R6kgME,10358
+memuron/actions/memory_write.py,sha256=YKp6i0LIVBYqPcov1ddMfjLh-945Xykwf6a_ST0SIYg,9534
+memuron/actions/nodes.py,sha256=bOcQmvhYyy3Y6rve2RbBI3vMoqUub7gjlZMfW3HIJHM,10712
+memuron/actions/registry.py,sha256=q1ND_FRoCrII4e2jXTc8Inds2HOmH0japHfi4aUfqLY,109
+memuron/actions/runtime.py,sha256=UNSwk1pXrP8RomsRPOUTT3KX7AB47dCJwO_ywIVsGcM,908
+memuron/actions/spaces_documents.py,sha256=rT__Vd8DsS8OxWoDzE3oE87L-0Bo0rGrqNX3NkGYkIY,22909
+memuron/actions/sync.py,sha256=zsFhpeF8RqmHhbdXuBY0CnBmQWt2N4p94YBOhHYbLSg,4779
+memuron/application/__init__.py,sha256=5P4r1E_-k8WWW8G0GJ8bWausjJw7VmG9fHC6IeZ2yis,68
+memuron/application/api.py,sha256=iKx7SXbS1xEZig8sMiDnslvlDJFjE-AByvDAt7rmgO0,7776
+memuron/application/app.py,sha256=_Nvae_wPKtAPStFKXvRNAvz4CPZQALuWdspvZBU3oFA,4075
+memuron/application/capabilities.py,sha256=bWLQTynWVmaQ59h7K1deB7ZNrOg0y9CIExi_TO6c9og,2676
+memuron/application/cli.py,sha256=_q4k3TtJejctKyxo18c3jASfBZAZAL1E-n9glIxHjWU,1201
+memuron/application/config.py,sha256=8zU4_1-xXCOIyVRphJQ7vocbLnz8XULVDFpcMwXGkpY,7289
+memuron/application/mcp.py,sha256=w3j6Td_WB7IBOTQrSO4bt_xPMOlTiO4GivJQ8N8yf7o,1234
+memuron/application/mcp_oauth.py,sha256=mKtwBf1jTvk0dFtW7qEn30eM_QF1zSgEFs8OKyKlDCk,10685
+memuron/application/registry.py,sha256=eN-JCfI5b5-oKkbklJRVhvXDPa4pbU_7SROfvVgyEpU,2019
+memuron/context.py,sha256=TRy-v9lnvskG_9CpR8TF_jKzlbvT2q_f2sjjKvnJ_Fo,16442
+memuron/documents/__init__.py,sha256=RI4li-GMS2zMN61hdsaS4BYOGJlwscBILvtpazbDpE4,75
+memuron/documents/link_guardian.py,sha256=upxx8xPpr94VynEe39FGBdbB0FEwRL5zmmyKrrtPh3I,6866
+memuron/documents/linking.py,sha256=Ml3BklEN91l7-mfvGFmLkvlgZnTBMqd2lV_GENqvmVs,9567
+memuron/documents/parser.py,sha256=nMmoJ-oUe86BDH-SnhdIPG71092jL1IjFFDdsTI9E5k,41138
+memuron/documents/storage.py,sha256=I9LrN6VJOmrm4IUN6AQI1LbGMK-W9qbYzQT_mkV3LMQ,4592
+memuron/documents/url_ingest.py,sha256=NohxeV7RKQjVjmFII4ENPEoTe3iMHkagfLfZT7tasm0,12716
+memuron/domain/__init__.py,sha256=cm7Jcksowm9UFFi4E6uvIxMECcBDeysBv1W_UXeF8r8,71
+memuron/domain/decoders.py,sha256=RTECAU_0aEGUTZMcBe-4u8wuU0eB3EAWOK6Kna8IXok,43
+memuron/domain/encoders.py,sha256=_gtuDn0fybFM753XTyqEQnOq4vD__O86LW6ytGSzqpw,6727
+memuron/domain/lifecycles.py,sha256=cCcdoU1Gmdo_bo-yzn-h-wJT4wGMnqoUkFByDEVlU2Q,397
+memuron/domain/limits.py,sha256=POH2nC65doANRWqALoLJDFjj6RMThAUklbQh6JYIVpE,154
+memuron/domain/representations.py,sha256=Y_AzUYa4vVNIlbKpH9H5ZT--IogvPzRaPB8oQmuRnJc,1583
+memuron/domain/schemas.py,sha256=cx7R4PWJCZ1_PxVIDbuLgzgNGtbdmVErIfsX8TZbEiE,17435
+memuron/domain/scope_filter.py,sha256=5CVoDJJG5a4wB0FmfeWvhwccbi8_WgPH_T_nOcsAUWE,3452
+memuron/graphfs/__init__.py,sha256=5W2hz6Eugt5AjX_SYkDHD4ndC4aBKZ8rtc3oln2uvH4,76
+memuron/graphfs/manual.py,sha256=WZFGEAuVvq9nF3yaGkOppK01lXyLEme6Vayx7GG67QA,28292
+memuron/graphfs/projection.py,sha256=U3xAKP3hDQM8HUKRizqAfzzLwQ7BI9VwjqG9LuKpJ2c,23231
+memuron/graphfs/query.py,sha256=XtHJohvYP8c0b5ZjROdtBm8BhZRqOVevF-NuEpevIaA,71044
+memuron/graphfs/read_model.py,sha256=74yk1rH-TI6MYoy6QVfUKLT_OCCWA5yvQE3_a800loE,17927
+memuron/ingest/__init__.py,sha256=TEIQXPab4cKDIYKIGZVkC2jW2jH2Jon-lGRQ4C3Cev4,71
+memuron/ingest/guardian.py,sha256=wNz9To2_jC5eLiu7dzPogouUaEOm3_GgbO-e-1dwOaU,8140
+memuron/ingest/jobs.py,sha256=O5yfcws2r3frDgOn-aMDGT7pnue-YPsXeJRSmaM_Z5w,15145
+memuron/ingest/prompts.py,sha256=YUQJeIxUW9zARUZp9qaty_1zk_dPP1_ShMdgnKcSDpo,5377
+memuron/memory/__init__.py,sha256=fErWrBOwv1XzXyTdDJP8lK37CmG1v6CxycJLEDOZU_8,67
+memuron/memory/engine.py,sha256=H7mWlxA8C6EDNOUYc-RxPRdXE8We09v3VCsTO0SvTHg,1118
+memuron/memory/projections.py,sha256=EVbua9n_WzTaZE8CsZ1PQF6KDVbzrCKkaIHsMDa7rRk,17978
+memuron/memory/recipes.py,sha256=tPpIlSaP9RvcDgdQhdanQ8mBc_ZOcr0uwkKR0vKzIJs,113174
+memuron/persistence/__init__.py,sha256=kwsZs154QTvUsV_2fsqkfJtJbRK0niFkV6tVk_Sb9Sk,68
+memuron/persistence/db_pool.py,sha256=bL9cmw_JBtFPUSsxo419NUR4xlr1zd1fN9TSdkINIFU,1842
+memuron/persistence/identity_store.py,sha256=lVLU9awJ8dQCNEqvaI7Jv0SpQo9cIeWf_8PmaAOcPic,35319
+memuron/persistence/store_helpers.py,sha256=5Scnn6GSnh7Bvxll_g-CxdmnMxVNJMMBbBLOrRZqnW0,635
+memuron/search/__init__.py,sha256=o1H6jl6QEY1umPkSl47pRGBQpusclXRIfS_15Tc1dYM,56
+memuron/search/fulltext.py,sha256=vEolp5s5tNz-IBInl0c_YPYYmMx-bOkHFWKu24jO3lI,3301
+memuron/search/hybrid.py,sha256=wU_nLnZ6tBOjxCut00A7h-MJb8AGybmCG6FI6QUxy7E,9759
+memuron/search/pgvector.py,sha256=7hrWUxSH4_Ki15d2_JYE-khbZDBUUlfd3x261QWrjEM,8198
+memuron/security/__init__.py,sha256=Men1S7LEuzD5EsiALh6FmOhi6073g21DBzrvA5s8t0Q,68
+memuron/security/auth.py,sha256=YPCZZDVtDCOkVcfQZQPME3CA8J7t9RaqPn9D0Vn8rhc,4740
+memuron/security/auth_provider.py,sha256=fVq4YC5MmTBL2t9DF2eJLVljicLKN7WkYRLBUR3yTzs,4213
+memuron/security/authorization.py,sha256=SyqciJXNYRcqfVjMIri3xGpgUZUU7Y0wOcM4zwmq1Wg,1573
+memuron/security/clerk_scopes.py,sha256=LeZR46-_mA443D2vEZPtVYdXPD9PMwqwfOvSRGGklvU,3002
+memuron/security/clerk_webhooks.py,sha256=My5zS1_MaC5nE5JuHlQOqvnh6WTFgdwTzb40GMw7GNY,2317
+memuron/security/jwt_tokens.py,sha256=dq0UdZw9M8dfLxE4IlmkJRjc_609ut0vjnsuzdior68,1337
+memuron/security/passwords.py,sha256=mrKiV84Vz9WFBxafJE1tEYvJFIKogsgKZyMAMODfvxs,988
+memuron/security/tenant.py,sha256=bpjZ3pdMteYffv3RgMcDMA9TmlE8w72YYmmtD-o7xWs,1667
+memuron/spaces/__init__.py,sha256=BfkEhQc0fvSZ5VYD8hTuY20MG6d1lmeZ24sTLl6UI7g,52
+memuron/spaces/model.py,sha256=HDwAfPTsxcnbaUeIMTBWX8-SzREIwfuKIr2Yls_ew-E,986
+memuron/spaces/service.py,sha256=FpeQULzZRbCBExf0Mlg_-g5k8cc39-kAissM61a2bTY,4870
+memuron/sync/__init__.py,sha256=gL7dLxgVSkHhuLnj3m0ZniEwoUkee9T-WbnmBeFHFzI,485
+memuron/sync/folder.py,sha256=Yasn4PPOyYM5MdQT8iKy1CwrzvSanNe4uopDBh5eX4s,27551
+memuron-0.1.1.dist-info/WHEEL,sha256=5w2T7AS2mz1-rW9CNagNYWRCaB0iQqBMYLwKdlgiR4Q,78
+memuron-0.1.1.dist-info/entry_points.txt,sha256=gAxxXUnTzi2Xm_jpdEwCDpL5ZPe-0YyXEYJ2mikkTto,101
+memuron-0.1.1.dist-info/METADATA,sha256=OpMGRGXJJAFlDNb0yRC2oxvIvbhMnu4JS5gwjckNpCc,9198
+memuron-0.1.1.dist-info/RECORD,,

memuron-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.9.7
+Root-Is-Purelib: true
+Tag: py3-none-any

memuron-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+memuron = memuron.application.cli:main
+memuron-mcp = memuron.application.mcp:main
+