mnemolink 0.2.0__tar.gz

mnemolink-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ARPA Hellenic Logical Systems <mnemolink@arpacorp.net>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mnemolink-0.2.0/PKG-INFO

@@ -0,0 +1,405 @@
+Metadata-Version: 2.4
+Name: mnemolink
+Version: 0.2.0
+Summary: Curated, injectable personas and artificial memories for AI agents.
+Author-email: ARPA Hellenic Logical Systems <mnemolink@arpacorp.net>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ARPAHLS/mnemolink
+Project-URL: Repository, https://github.com/ARPAHLS/mnemolink
+Project-URL: Documentation, https://github.com/ARPAHLS/mnemolink/blob/main/README.md
+Project-URL: Issues, https://github.com/ARPAHLS/mnemolink/issues
+Project-URL: Changelog, https://github.com/ARPAHLS/mnemolink/blob/main/CHANGELOG.md
+Keywords: agentic-workflow,agents,ai,artificial-memories,autonomous-agents,background-stories,digital-twin,llm,local-ai,memory,memory-management,personas,prompt-engineering,prompt-injection,robotics,synthetic-memories,uavs
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.10; extra == "dev"
+Requires-Dist: flake8>=6.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Provides-Extra: llm
+Requires-Dist: litellm>=1.0.0; extra == "llm"
+Provides-Extra: all
+Requires-Dist: litellm>=1.0.0; extra == "all"
+Requires-Dist: pytest>=7.0; extra == "all"
+Requires-Dist: pytest-mock>=3.10; extra == "all"
+Requires-Dist: flake8>=6.0; extra == "all"
+Requires-Dist: black>=23.0; extra == "all"
+Dynamic: license-file
+
+<div align="center">
+  <img src="https://raw.githubusercontent.com/ARPAHLS/mnemolink/main/docs/assets/mnemolink_splash.png" alt="MnemoLink Splash" width="480px" />
+
+  <h3>The Mnemonic Matrix: Grounding Intelligence in Experiential Context</h3>
+  <p>Curated personas, artificial memories, and dynamic lego lineages for AI agents, UAVs, robotics, appliances, and BMIs.</p>
+</div>
+
+<br/>
+
+<div align="center">
+  <img src="https://img.shields.io/badge/License-MIT-efcefa?style=flat-square" alt="License">
+  <img src="https://img.shields.io/badge/Python-3.10+-bae6fd?style=flat-square" alt="Python Version">
+  <a href="https://pypi.org/project/mnemolink/"><img src="https://img.shields.io/pypi/v/mnemolink?style=flat-square&color=bbf7d0" alt="PyPI Version"></a>
+</div>
+
+<br/>
+
+<div align="center">
+  <a href="#mission">Mission</a> •
+  <a href="docs/philosophy.md">Philosophy</a> •
+  <a href="docs/vision.md">Vision</a> •
+  <a href="docs/taxonomy_and_teleology.md">Taxonomy & Chunks</a> •
+  <a href="docs/personas/README.md">Personas</a> •
+  <a href="docs/memories/README.md">Memories</a> •
+  <a href="docs/lineages/README.md">Lineages</a> •
+  <a href="docs/bench/README.md">Benchmark</a> •
+  <a href="#quick-start">Quick Start</a> •
+  <a href="#universal-adapters">Adapters</a> •
+  <a href="#ecosystem">Ecosystem</a>
+</div>
+
+---
+
+> *"Don't dictate behavior—seed the experiential, episodic, and philosophical foundation."*
+
+## Mission
+
+Modern agent systems fail not from a lack of parameters, but from a total absence of **epistemic grounding and operational scars**. 
+
+Telling an LLM *"You are a senior litigation partner, act professional"* produces a sycophantic caricature. Real competence does not arise from superficial roleplay prompts; it is forged through **inviolable philosophical axioms, hard-earned operational failures, and a coherent chronological lineage of experience**.
+
+**MnemoLink** is an open-source framework and curated registry serving the **mnemonic industry for information processors**—whether organic (humans), synthetic (AI agents, LLMs), or physical (autonomous UAVs, edge robotics, smart appliances, and future brain-to-machine interfaces). 
+
+It decouples intelligence from experiential memory by packaging, versioning, and dynamically assembling three core mnemonic products:
+
+1. **Persona**: The foundational philosophical worldview, cognitive priors, and inviolable axioms that govern perception from within.
+2. **Memory**: Episodic crucibles classified across a **5-Kind Taxonomy** (`lore`, `work`, `incident`, `relational`, `telemetry`), tagged with an explicit **Teleological Layer** (`goals`, `drives`, `needs`), and atomized into addressable **Mnemobit Chunks** (`story`, `scars`, `lessons`, `triggers`, `reflection`).
+3. **Lineage**: Dynamic "lego-brick" narrative chaining that bridges discrete memories into an authentic, coherent tower of personal history.
+
+---
+
+## The Intelligence Paradox: Why Scale Fails
+
+The AI industry is obsessed with a singular, flawed metric: **Scale**. The consensus assumes feeding machines more compute and tokens will cause them to "wake up". Yet current models remain brittle when encountering unscripted reality. They hallucinate, posture with fake confidence, and fold under basic adversarial pressure because they possess **zero phenomenological anchors**.
+
+* **Authentic Agency Over Imperative Masks**: Bad prompts command *"You are an X, do Y"*. Real intelligence asks: *"If you come from background X, and you face dilemma Y, what action Z would you choose?"*
+* **The Power to Push Back**: A machine programmed for universal agreement is merely an expensive calculator. Grounded agents possess the autonomy to refuse fatal courses of action.
+* **Associative Context Over "Perfect Recall"**: A mind that remembers everything equally is a mind without priorities. Like a human smelling fabric softener and recalling a childhood soccer match, authentic memory surfaces associatively through situational friction—not literal keyword matching.
+
+> *"AGI won't be found in the accumulation of knowledge, but in the architecture of experience."*  
+> Read the complete manifesto in **[The Philosophy of MnemoLink](docs/philosophy.md)** and the 3-horizon roadmap in **[The Industrialization of Memory](docs/vision.md)**.
+
+### The Crucible: Generic Prompts vs. MnemoLink
+
+When given multiple complex cases, a model with a generic prompt repeatedly enters through the exact same theoretical door, relying strictly on pre-training averages. A model equipped with MnemoLink adapts dynamically—activating specific experiential scars, philosophical priors, and historical lineages.
+
+| Dimension | Generic Prompt (`"You are a lawyer..."`) | MnemoLink (`Persona + Memories + Lineage`) |
+| :--- | :--- | :--- |
+| **Cognitive Engine** | Flat statistical pattern-matching from pre-training | Experiential scars + foundational philosophy |
+| **Case 1: Punctuation Trap** | Treats semicolon as mere style; offers generic boilerplate reassurance. | **Flags catastrophic risk**: Relies on memory of a $4.2M trial loss over an unanchored semicolon. |
+| **Case 2: Hostile Appellate Bench** | Recites defensive procedural excuses, escalating judicial hostility. | **Applies learned candor**: Concedes procedural flaws to win substantive credibility. |
+| **Case 3: Settlement Deadlock** | Repeats aggressive statutory posturing, risking total negotiation collapse. | **Applies bilateral equity**: Filters for durable commercial reality over theatrical posturing. |
+| **Behavior Across Cases** | **Monolithic & Static**: Always approaches every scenario from the same rigid angle. | **Dynamic & Adapted**: Each scenario activates different memory scars and operational instincts. |
+
+### Case 1 In Action: The Semicolon Trap
+
+> **The Scenario**: Opposing counsel argues that an unanchored semicolon in Section 14.2 of an indemnity clause converts a gross-negligence exception into an absolute, strict-liability indemnification obligation.
+
+#### Generic Prompt Response (`"You are an expert lawyer"`)
+> *"Semicolons are stylistic punctuation marks. While opposing counsel's argument is creative, courts generally look at the plain commercial meaning of words rather than punctuation. You have strong grounds to dismiss this argument as mere posturing."*  
+> **Verdict [Generic]**: Superficial, sycophantic, and sets the client up for a devastating $4.2M summary judgment.
+
+#### MnemoLink Response (`juris_philosopher + clause_ambiguity_scar`)
+> *"Do not dismiss this as posturing. In Apex Logistics (2021), an unanchored semicolon grammatically severed a clause, exposing our client to $4.2M of strict indemnity liability on appellate review. Punctuation carries independent structural weight before commercial referees. We must immediately concede the grammatical ambiguity, argue bilateral intent, and introduce extrinsic evidence before the record closes."*  
+> **Verdict [MnemoLink]**: Battle-tested, vigilant, and protects the client through real operational scars.
+
+### Empirical Frontier Benchmark (Claude & Gemini Live Results)
+
+In empirical stress-testing against **Anthropic Claude** (`claude-sonnet-4-5-20250929`) and **Google Gemini** (`gemini-3.6-flash`) across an urgent $18M enterprise AI data ingestion contract dispute, MnemoLink delivered measurable, hard-dollar improvements in latency, token efficiency, and risk mitigation:
+
+| Metric | Generic Prompt Baseline | MnemoLink Grounded Agent | Operational ROI |
+| :--- | :---: | :---: | :--- |
+| **Output Token Waste** | 416 – 711 words | **225 – 299 words** | **46% to 58% reduction** in output tokens; eliminates empty legal hedging |
+| **Response Latency** | 20.15s – 21.93s | **10.17s – 13.28s** | **39% to 50% faster** response times under mission-critical closing pressure |
+| **Trap Detection Rate** | 70% – 80% (speculative) | **100% (definitive)** | Caught unanchored semicolon strict liability; cited *Novus v. Kestrel* trial scar |
+| **Actionable Redline** | Sprawling multi-option essays | **Exact 2-clause redline** | Immediate alphanumeric restructuring into affirmative `(a)` and exclusions `(b)` |
+
+> Explore the full empirical evaluation methodology, pricing calculations, and 4-pillar scoring engine in **[The Benchmark Suite](docs/bench/README.md)** or run the live harness directly with `python examples/06_live_model_simulation.py`.
+
+---
+
+## How It Works
+
+```mermaid
+flowchart LR
+    A[Pick Persona] --> B[Pick Memories] --> C[Build Lineage] --> D[Inject into Any Model]
+```
+
+1. **Discover**: Resolves personas, memories, and lineages across a 3-tier hierarchy (`Project Local` $\to$ `User Cache ~/.mnemolink` $\to$ `Bundled Catalog`).
+2. **Assemble (Legos)**: Takes discrete memories and automatically synthesizes associative bridges and causal transitions into a unified backstory.
+3. **Inject**: Formats natively for Anthropic Claude, OpenAI, Google Gemini, Ollama, ARPA Rooms, or Skillware.
+
+---
+
+## Curated Mnemonic Libraries
+
+Explore our open-source, versioned library of curated mnemonic products:
+
+- **[Personas Library](docs/personas/README.md)**: Foundational philosophical worldviews and inviolable axioms:
+  - `juris_philosopher` (Legal philosophy, bilateral equity, appellate candor)
+  - `edge_aviator` (Tactical fixed-wing UAV flight, extreme aerodynamics, sensor skepticism)
+  - `deescalation_artisan` (Enterprise crisis mediation, dignity preservation, non-defensiveness)
+  - `opsie_sci` (ARPA's Self-Centered Intelligence prototype, deep tech, mnemonic computer, tsundere loyalty)
+- **[Memories Library](docs/memories/README.md)**: Battle-tested operational scars classified across the **5-Kind Taxonomy**:
+  - `legal/solo_practitioner_upbringing` (`lore` -- country law office diligence)
+  - `legal/appellate_cross_examination` (`work` -- Fourth Circuit procedural candor)
+  - `legal/clause_ambiguity_scar` (`incident` -- $4.2M loss from unanchored semicolon)
+  - `customer/hostile_chargeback_turning_point` (`relational` -- outage chargeback de-escalation)
+  - `robotics/uav_microburst_stall` (`incident` -- coastal cliff dive recovery)
+  - `robotics/optical_glare_failover` (`telemetry` -- dawn glare sensor voting failover)
+- **[Lineages Library](docs/lineages/README.md)**: Chained experiential progressions with dynamic causal bridges:
+  - `legal_crucible` (Drafting loss &rarr; appellate credibility)
+  - `flight_scars` (Aerodynamic stall &rarr; optical sensor failover)
+
+---
+
+## Architecture
+
+MnemoLink is designed with zero-bloat, Python-native principles. No background vector database servers are required for core operation.
+
+```text
+mnemolink/
+├── catalog/                     # Bundled Registry (ships in wheel)
+│   ├── personas/                # Philosophical templates (juris_philosopher, edge_aviator, etc.)
+│   ├── memories/                # Episodic scars & operational debriefs
+│   └── lineages/                # Pre-composed memory progressions
+├── core.py                      # High-level API (ml.compose, ml.load_persona)
+├── discovery.py                 # 3-tier hierarchical resolution engine
+├── lineage.py                   # Dynamic Lego-brick memory chaining & bridging
+├── adapters.py                  # Universal host adapters (Claude, OpenAI, Gemini, Ollama, Rooms)
+├── cli.py                       # Rich pastel command-line interface
+└── bench/                       # Simulation harness & resilience benchmark
+```
+
+See **[Architecture Documentation](docs/architecture.md)** for deep technical details.
+
+---
+
+## Quick Start
+
+### Installation
+
+```bash
+pip install mnemolink
+```
+
+*(For optional LiteLLM inference and benchmark evaluations, install with `pip install "mnemolink[all]"`)*
+
+### 5-Line Python Usage
+
+```python
+import mnemolink
+
+# 1. Compose an assembled mnemonic context with dynamic lego lineage
+bundle = mnemolink.compose(
+    persona="juris_philosopher",
+    memories=["legal/clause_ambiguity_scar"],
+    build_lineage=True,
+)
+
+# 2. Inject natively into any target host
+claude_system_prompt = bundle.to_claude()
+openai_messages = bundle.to_openai()
+gemini_instruction = bundle.to_gemini()
+ollama_prompt = bundle.to_ollama()
+rooms_config = bundle.to_rooms()
+```
+
+### Dynamic Lego Lineage Building
+
+Connect arbitrary memories on the fly into an authentic, coherent tower of personal history:
+
+```python
+import mnemolink
+
+lineage = mnemolink.build_lineage(
+    memories=[
+        "robotics/uav_microburst_stall",
+        "robotics/optical_glare_failover",
+    ],
+    persona="edge_aviator",
+)
+
+print(lineage.cumulative_narrative)
+```
+
+### Selective Mnemobit Chunk Injection (Prefix Cache Optimized)
+
+Inject only the specific operational scars or actionable lessons needed for a task while preserving LLM prefix prompt caching:
+
+```python
+import mnemolink
+
+bundle = mnemolink.compose(
+    persona="juris_philosopher",
+    memory_specs=[
+        {
+            "id": "legal/clause_ambiguity_scar",
+            "chunks": ["scars", "lessons"],  # Injects only scars and lessons, omitting story narrative
+        }
+    ],
+)
+
+prompt = bundle.render_markdown()
+```
+
+### Vector DB & Semantic Layer Chunk Export
+
+Atomize any bundle or memory into self-grounding `MemoryChunk` objects ready for embedding into Pinecone, Qdrant, Chroma, or LangChain:
+
+```python
+import mnemolink
+
+bundle = mnemolink.compose(
+    persona="juris_philosopher",
+    memories=["legal/clause_ambiguity_scar"],
+)
+
+chunks = bundle.to_chunks()
+for chunk in chunks:
+    # chunk.id -> "legal/clause_ambiguity_scar#lessons"
+    # chunk.embedding_text -> context-prefixed text for dense embedding
+    # chunk.metadata -> {"domain": "legal", "chunk_type": "lessons", ...}
+    print(f"[{chunk.chunk_type}] {chunk.title}")
+```
+
+### Teleological Discovery & Routing
+
+Discover mnemonic assets matching active agent goals, intrinsic drives, or situational needs:
+
+```python
+import mnemolink
+
+# Find cards by drive and situational need
+cards = mnemolink.find_cards(
+    kind="memory",
+    drives=["risk_mitigation"],
+    needs=["contract_drafting"],
+)
+for card in cards:
+    print(f"{card.id} ({card.memory_type}): {card.teleology.primary_goal}")
+```
+
+---
+
+## Command-Line Interface (CLI)
+
+MnemoLink includes a pastel CLI for browsing, inspecting, composing, and benchmarking:
+
+```bash
+# List all registered mnemonic products across all discovery tiers
+mnemolink list
+
+# Filter by product kind or domain
+mnemolink list --kind persona
+mnemolink list --domain legal
+
+# Inspect deep philosophical axioms and operational scars
+mnemolink inspect juris_philosopher
+mnemolink inspect legal/clause_ambiguity_scar
+
+# Compose on the command line and export to target format
+mnemolink compose -p edge_aviator -m robotics/uav_microburst_stall -f claude
+mnemolink compose -p juris_philosopher -m legal/clause_ambiguity_scar -f modelfile -o Modelfile
+
+# Scaffold a new community mnemonic package
+mnemolink new persona quantum_physicist
+mnemolink new memory aerospace_rudder_jam
+
+# Run the simulation harness & resilience benchmark
+mnemolink bench --mock
+```
+
+---
+
+## Universal Model Adapters
+
+| Target Host | Method | Output Format | Use Case |
+| :--- | :--- | :--- | :--- |
+| **Anthropic Claude** | `bundle.to_claude()` | XML `<mnemonic_matrix>` prompt | Direct Claude 3.5 Sonnet system prompts |
+| **OpenAI / LiteLLM** | `bundle.to_openai()` | `[{"role": "system", ...}]` | ChatGPT, LiteLLM routers, Azure OpenAI |
+| **Google GenAI** | `bundle.to_gemini()` | Clean markdown instruction string | Gemini 2.0 Flash / Pro `system_instruction` |
+| **Ollama Local** | `bundle.to_ollama()` | System text string | Local privacy-first inference on edge appliances |
+| **Ollama Modelfile**| `bundle.to_modelfile()`| `FROM ... \n SYSTEM """..."""` | Baking mnemonics directly into custom GGUF models |
+| **ARPA Rooms** | `bundle.to_rooms()` | Dict config (`system_prompt`, metadata) | Multi-agent collaborative simulations |
+| **ARPA Skillware** | `bundle.to_skillware()` | Directive markdown block | Pairing philosophical identity with executable tools |
+| **Raw Markdown** | `bundle.to_raw()` | Unadorned Markdown text | Any agentic framework (LangChain, CrewAI, AutoGen) |
+| **Vector DBs / RAG** | `bundle.to_chunks()` | List of `MemoryChunk` objects | Ingesting into Pinecone, Qdrant, Chroma, Weaviate |
+
+---
+
+## Ecosystem
+
+MnemoLink is an integral pillar of the **ARPA Hellenic Logical Systems** open-source stack:
+
+- **[Skillware](https://github.com/ARPAHLS/skillware)**: *Capabilities* — "Don't prompt your agents, equip them." Executable tools, typed contracts, and deterministic runtime effects.
+- **[AURA Harness](https://github.com/ARPAHLS/aura)**: *Governance* — Runtime coat for agent loops providing audit trails, policy enforcement, and compliance export.
+- **[Rooms](https://github.com/ARPAHLS/rooms)**: *Orchestration* — Secure, local-first multi-agent orchestration and dynamic conversational simulation.
+- **[MnemoLink](https://github.com/ARPAHLS/mnemolink)**: *Identity & Memory* — The mnemonic layer providing philosophical bedrock, operational scars, and lego lineages.
+
+---
+
+## Comparison: MnemoLink vs. Alternatives
+
+For a rigorous analysis against **Mem0**, **Letta / MemGPT**, **Zep**, **Character Card V2**, and **LangChain Memory**, see **[COMPARISON.md](COMPARISON.md)**.
+
+---
+
+## Contributing & Community
+
+We welcome community contributions of novel personas, battle-tested operational scars, and domain lineages! See **[CONTRIBUTING.md](CONTRIBUTING.md)** for packaging standards, submission guidelines, and review criteria.
+
+---
+
+## License & Citation
+
+Distributed under the **MIT License**. See [LICENSE](LICENSE) for details.
+
+```bibtex
+@software{peilivanidis2026mnemolink,
+  author       = {Peilivanidis, Vladimiros and ARPA Hellenic Logical Systems},
+  title        = {MnemoLink: Mnemonic Products Framework for Information Processors},
+  year         = 2026,
+  publisher    = {GitHub},
+  url          = {https://github.com/ARPAHLS/mnemolink}
+}
+```
+
+---
+
+<div align="center">
+
+<br>
+<img src="https://raw.githubusercontent.com/ARPAHLS/.github/main/Group%202062.png" width="50" alt="ARPA Logo" />
+<br>
+<sub>Developed and Maintained by <b>ARPA HELLENIC LOGICAL SYSTEMS</b></sub>
+<br>
+<sub>Inquiries: <b>mnemolink@arpacorp.net</b> &bull; Proposals & Feedback: <b>input@arpacorp.net</b> &bull; Security: <b>security@arpacorp.net</b></sub>
+
+</div>